NI-FBUSTM Function Reference Manual for Windows NT

NI-FBUSTM

Function ReferenceManual for Windows NT

December 1996 EditionPart Number 321288A-01

© Copyright 1996 National Instruments Corporation.All Rights Reserved.

Internet [email protected]

E-mail: [email protected]

FTP Site: ftp.natinst.com

Web Address: http://www.natinst.com

Bulletin Board SupportBBS United States: (512) 794-5422BBS United Kingdom: 01635 551422BBS France: 01 48 65 15 59

Fax-on-Demand Support(512) 418-1111

Telephone Support (U.S.)Tel: (512) 795-8248Fax: (512) 794-5678

International OfficesAustralia 03 9879 5166, Austria 0662 45 79 90 0, Belgium 02 757 00 20,Canada (Ontario) 905 785 0085, Canada (Québec) 514 694 8521, Denmark 45 76 26 00,Finland 09 527 2321, France 01 48 14 24 24, Germany 089 741 31 30,Hong Kong 2645 3186, Israel 03 5734815, Italy 02 413091, Japan 03 5472 2970,Korea 02 596 7456, Mexico 5 520 2635, Netherlands 0348 433466,Norway 32 84 84 00, Singapore 2265886, Spain 91 640 0085, Sweden 08 730 49 70,Switzerland 056 200 51 51, Taiwan 02 377 1200, U.K. 01635 523545

National Instruments Corporate Headquarters6504 Bridge Point Parkway Austin, TX 78730-5039 Tel: (512) 794-0100

Important Information

WarrantyThe media on which you receive National Instruments software are warranted not to fail to execute programminginstructions, due to defects in materials and workmanship, for a period of 90 days from date of shipment, as evidenced byreceipts or other documentation. National Instruments will, at its option, repair or replace software media that do notexecute programming instructions if National Instruments receives notice of such defects during the warranty period.National Instruments does not warrant that the operation of the software shall be uninterrupted or error free.

A Return Material Authorization (RMA) number must be obtained from the factory and clearly marked on the outside ofthe package before any equipment will be accepted for warranty work. National Instruments will pay the shipping costs ofreturning to the owner parts which are covered by warranty.

National Instruments believes that the information in this manual is accurate. The document has been carefully reviewedfor technical accuracy. In the event that technical or typographical errors exist, National Instruments reserves the right tomake changes to subsequent editions of this document without prior notice to holders of this edition. The reader shouldconsult National Instruments if errors are suspected. In no event shall National Instruments be liable for any damagesarising out of or related to this document or the information contained in it.

EXCEPT AS SPECIFIED HEREIN, NATIONAL INSTRUMENTS MAKES NO WARRANTIES, EXPRESS ORIMPLIED, AND SPECIFICALLY DISCLAIMS ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR APARTICULAR PURPOSE. CUSTOMER’S RIGHT TO RECOVER DAMAGES CAUSED BY FAULT ORNEGLIGENCE ON THE PART OF NATIONAL INSTRUMENTS SHALL BE LIMITED TO THE AMOUNTTHERETOFORE PAID BY THE CUSTOMER. NATIONAL INSTRUMENTS WILL NOT BE LIABLE FORDAMAGES RESULTING FROM LOSS OF DATA, PROFITS, USE OF PRODUCTS, OR INCIDENTAL ORCONSEQUENTIAL DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. This limitation of the liabilityof National Instruments will apply regardless of the form of action, whether in contract or tort, including negligence. Anyaction against National Instruments must be brought within one year after the cause of action accrues. National Instrumentsshall not be liable for any delay in performance due to causes beyond its reasonable control. The warranty provided hereindoes not cover damages, defects, malfunctions, or service failures caused by owner’s failure to follow the NationalInstruments installation, operation, or maintenance instructions; owner’s modification of the product; owner’s abuse,misuse, or negligent acts; and power failure or surges, fire, flood, accident, actions of third parties, or other events outsidereasonable control.

CopyrightUnder the copyright laws, this publication may not be reproduced or transmitted in any form, electronic or mechanical,including photocopying, recording, storing in an information retrieval system, or translating, in whole or in part, withoutthe prior written consent of National Instruments Corporation.

TrademarksNI-FBUS™ is a trademark of National Instruments Corporation.

Product and company names listed are trademarks or trade names of their respective companies.

WARNING REGARDING MEDICAL AND CLINICAL USE OF NATIONAL INSTRUMENTS PRODUCTSNational Instruments products are not designed with components and testing intended to ensure a level of reliabilitysuitable for use in treatment and diagnosis of humans. Applications of National Instruments products involving medical orclinical treatment can create a potential for accidental injury caused by product failure, or by errors on the part of the useror application designer. Any use or application of National Instruments products for or involving medical or clinicaltreatment must be performed by properly trained and qualified medical personnel, and all traditional medical safeguards,equipment, and procedures that are appropriate in the particular situation to prevent serious injury or death should alwayscontinue to be used when National Instruments products are being used. National Instruments products are NOT intendedto be a substitute for any form of established process, procedure, or equipment used to monitor or safeguard human healthand safety in medical or clinical treatment.

© National Instruments Corporation v NI-FBUS FRM for Windows NT

Tableof

Contents

About This ManualHow to Use the Manual Set ..........................................................................................ixOrganization of This Manual.........................................................................................xConventions Used in This Manual.................................................................................xRelated Documentation..................................................................................................xiCustomer Communication .............................................................................................xi

Chapter 1Administrative Functions

Format of the Function Information ..............................................................................1-1Function Names...............................................................................................1-1Purpose ............................................................................................................1-1Format .............................................................................................................1-1Input ................................................................................................................1-1Output..............................................................................................................1-1Context ............................................................................................................1-2Description ......................................................................................................1-2Return Values ..................................................................................................1-2

nifClose..........................................................................................................................1-3nifGetBlockList .............................................................................................................1-5nifGetDeviceList............................................................................................................1-8nifGetInterfaceList.........................................................................................................1-11nifGetVFDList ...............................................................................................................1-13nifOpenBlock.................................................................................................................1-15nifOpenLink...................................................................................................................1-17nifOpenPhysicalDevice .................................................................................................1-19

Table of Contents

NI-FBUS FRM for Windows NT vi © National Instruments Corporation

nifOpenSession..............................................................................................................1-21nifOpenVfd....................................................................................................................1-23

Chapter 2Core Fieldbus Functions

nifFreeObjectAttributes.................................................................................................2-2nifGetObjectAttributes ..................................................................................................2-3nifGetObjectSize ...........................................................................................................2-7nifGetObjectType..........................................................................................................2-10nifReadObject................................................................................................................2-17nifWriteObject...............................................................................................................2-21Using Interface Macros .................................................................................................2-25

Chapter 3Alert and Trend Functions

nifAcknowledgeAlarm ..................................................................................................3-2nifWaitAlert...................................................................................................................3-4nifWaitTrend .................................................................................................................3-7

AppendixCustomer Communication

Glossary

Index

TablesTable 1-1. List of Administrative Functions .............................................................1-2

Table 2-1. List of Core Functions .............................................................................2-1Table 2-2. Object Codes for the nifObjTypeList_t Data Structure ...........................2-13Table 2-3. Standard Data Types for Objects with

the Object Code ODT_SIMPLETYPE ....................................................2-15

Table of Contents

© National Instruments Corporation vii NI-FBUS FRM for Windows NT

Table 2-4. Core Function Macros ..............................................................................2-25

Table 3-1. List of Alert Functions .............................................................................3-1Table 3-2. Trend Function .........................................................................................3-1

© National Instruments Corporation ix NI-FBUS FRM for Windows NT

AboutThis

Manual

This manual describes the NI-FBUS functions of the NI-FBUS softwarefor Windows NT. The NI-FBUS software for Windows NT is meant to beused with Windows NT version 3.51 or higher. This manual assumes thatyou are already familiar with the Windows NT operating system.

Getting StartedManual

Installation andConfiguration

NI-FBUSUser Manual for

Windows NT

ApplicationDevelopmentand Utilities

NoviceUsers

ExperiencedUsers

NI-FBUS FunctionReference Manualfor Windows NT

Functionand StructureDescriptions

How to Use the Manual SetUse this Function Reference Manual to look up specific informationabout NI-FBUS functions, such as input and output parameters, syntax,and error messages.

About This Manual

NI-FBUS FRM for Windows NT x © National Instruments Corporation

Use the Getting Started manual to install and configure your fieldbusinterface and the NI-FBUS software for Windows NT.

Use the NI-FBUS User Manual for Windows NT to learn how to use theNI-FBUS interface for your application.

Organization of This ManualThis manual is organized as follows:

• Chapter 1, Administrative Functions, includes a list of availableNI-FBUS administrative functions, and describes the purpose,format, input and output arguments, context, description, and returnvalues for each function.

• Chapter 2, Core Fieldbus Functions, lists and describes the coreNI-FBUS functions.

• Chapter 3, Alert and Trend Functions, lists and describes theNI-FBUS alert and trend functions.

• The Appendix, Customer Communication, contains forms you canuse to request help from National Instruments or to comment on ourproducts and manuals.

• The Glossary contains an alphabetical list and description of termsused in this manual, including abbreviations, acronyms, metricprefixes, mnemonics, and symbols.

• The Index contains an alphabetical list of key terms and topics in thismanual, including the page where you can find each one.

Conventions Used in This ManualThis manual uses the following conventions:

bold italic Bold italic text denotes a note, caution, or warning.

bold Bold text in this font denotes the messages and responses thatmonospace the computer automatically prints to the screen. This font also

emphasizes lines of code that are unique.

italic Italic text denotes emphasis, a cross reference, or an introduction to a keyconcept. This font also denotes text for which you supply the appropriateword or value.

About This Manual

© National Instruments Corporation xi NI-FBUS FRM for Windows NT

italic Italic text in this font denotes that you must supply the appropriate wordsmonospace or values in the place of these items.

monospace Text in this font denotes text or characters that you should enter from thekeyboard, sections of code, programming examples, and syntaxexamples. This font is also used for the proper names of disk drives,paths, directories, programs, subprograms, subroutines, device names,functions, operations, variables, filenames and extensions, and forstatements and comments taken from programs.

NI-FBUS In this manual, the term NI-FBUS refers to the NI-FBUSCommunications Manager.

Related DocumentationThe following documents contain information that you might find helpfulas you read this manual:

• Function Block Application Process, Part 1

• Function Block Application Process, Part 2

• Device Description Services Specification, Fieldbus Foundation

• Fieldbus Message Specification, Fieldbus Foundation

Customer CommunicationNational Instruments wants to receive your comments on our productsand manuals. We are interested in the applications you develop with ourproducts, and we want to help if you have problems with them. To makeit easy for you to contact us, this manual contains comment andconfiguration forms for you to complete. These forms are in theAppendix, Customer Communication, at the end of this manual.

© National Instruments Corporation 1-1 NI-FBUS FRM for Windows NT

Administrative Functions1

Chapter

This chapter includes a list of available NI-FBUS administrative functions, and describesthe purpose, format, input and output arguments, context, description, and return values foreach function.

For details on how NI-FBUS functions are classified and how to use them, refer to theNI-FBUS User Manual for Windows NT.

Format of the Function Information

Function NamesThe functions are in alphabetical order in each chapter.

PurposeThe Purpose sections are brief statements of the purpose of each function.

FormatThe Format sections show the format for calling each function.

InputThe Input sections show the input parameters for each function.

OutputThe Output sections show the output parameters for each function.

Chapter 1 Administrative Functions

NI-FBUS FRM for Windows NT 1-2 © National Instruments Corporation

ContextThe Context sections tell you if you can use a function on a link, device, VFD, session, orphysical device.

DescriptionThe Description sections describe the purpose and workings of each function.

Return ValuesThe Return Values sections list all the return values for each function and explain whateach one means.

Table 1-1. List of Administrative Functions

Function Purpose

nifClose Close an open descriptor

nifGetBlockList Return a list of information for all blocks of thespecified type present in the VFD

nifGetDeviceList Return the list of information for all activedevices on the network

nifGetInterfaceList Read the list of interface names from theNI-FBUS configuration

nifGetVFDList Gather VFD information on a specifiedphysical device

nifOpenBlock Return a descriptor representing a block

nifOpenLink Return a descriptor representing a fieldbus link

nifOpenPhysicalDevice Return a descriptor representing a physicaldevice

nifOpenSession Return a descriptor for an NI-FBUS session

nifOpenVfd Return a descriptor representing a Virtual FieldDevice (VFD)



nifClose

PurposeClose an open descriptor.

FormatnifError_t nifClose(nifDesc_t ud)

Inputud The descriptor from an nifOpen call.

OutputNot applicable.

ContextBlock, VFD, physical device, link, session.

DescriptionnifClose closes the specified descriptor. The descriptor is invalid after it is closed. Besure your application closes all the descriptors it opens. Your application should alwaysclose a descriptor if it no longer needs the descriptor.

If you close a descriptor with calls pending on it, the calls complete within the usual timewith an error code indicating that you closed the descriptor prematurely. If you make moresynchronous wait calls that wait on the closing descriptor, such as nifWaitTrend ,nifWaitAlert , and nifGetDeviceList , NI-FBUS aborts these functions and returns anerror code indicating that you closed the descriptor. Because calls that wait on a closeddescriptor return an error message, you should have a separate descriptor just for thesesynchronous wait calls.

Note: A session is a connection between your application and an NI-FBUSentity. If you close a session, you close the communication channelbetween your application and the NI-FBUS entity associated with thesession. Make sure you close all descriptors opened under this sessionbefore closing a session descriptor.



nifCloseContinued

Return ValuesE_OK The call was successful.

E_INVALID_DESCRIPTOR The descriptor is invalid.

E_SERVER_CONNECTION_LOST The session established with NI-FBUS for thisdescriptor has been closed or lost.



nifGetBlockList

PurposeReturns a list of information for all blocks of the specified type present in the VFD.

FormatnifError_t nifGetBlockList(nifDesc_t ud, uint8 whichTypes,

nifBlockInfo_t *info, uint16 *numBlocks)

Inputud The descriptor of a VFD.whichTypes Specifies what types of blocks to return (function,

transducer, or physical).numBlocks The number of buffers allocated in the info list.

Outputinfo The list of information associated with each block.numBlocks The number of blocks actually in the VFD.

ContextVFD.

DescriptionnifGetBlockList returns information about all the blocks in the specified VFD. A blockcan be a resource block, transducer block, or function block residing within a VFD. Onlyblocks of the types specified by whichTypes are returned.



nifGetBlockListContinued

nifBlockInfo_t is defined as follows:

typedef struct {char fbTag[TAG_SIZE + 1];uint16 startIndex;uint32 ddName;uint32 ddItem;uint16 ddRev;uint16 profile;uint16 profileRev;uint32 executionTime;uint32 periodExecution;uint16 numParams;uint16 nextFb;uint16 startViewIndex;uint8 numView3;uint8 numView4;uint16 ordNum;uint8 blockType;

} nifBlockInfo_t;

The blockType field in nifBlockInfo_t can be FUNCTION_BLOCK,TRANSDUCER_BLOCK, or RESOURCE_BLOCK.

The whichTypes parameter must be a bit combination of FUNCTION_BLOCK,TRANSDUCER_BLOCK, and RESOURCE_BLOCK.


E_INVALID_DESCRIPTOR The descriptor was invalid or of the wrong type.

E_COMM_ERROR NI-FBUS failed to communicate with the device.

E_BUF_TOO_SMALL The buffer does not contain enough entries to holdall the information for the blocks. If you receivethis error, buffer entries that you allocated do notcontain valid block information when the callreturns.



nifGetBlockListContinued

E_OBSOLETE_DESC The input descriptor is no longer valid. It wasclosed before nifGetBlockList completed.

E_BAD_ARGUMENT The whichtypes value is something other thanFUNCTION_BLOCK, TRANSDUCER_BLOCK, orRESOURCE_BLOCK.

E_RESOURCES A system resource problem occurred. The resourceproblem is usually a memory shortage.

E_BAD_DEVICE_DATA The device returned some inconsistent information.




nifGetDeviceList

PurposeReturn the list of information for all active devices on the network.

FormatnifError_t nifGetDeviceList(nifDesc_t link,

nifDeviceInfo_t *devInfo, uint16 *numDevices,uint16 *revision)

Inputlink The link descriptor to return information for.numDevices The number of allocated list entries.revision The revision number from the last

nifGetDeviceList call, or zero (see theDescription for usage).

OutputdevInfo The list of device information.numDevices The number of devices present in the link.revision Current revision number of the live list that

NI-FBUS reads from the fieldbus interface to thespecified link.

ContextLink.

DescriptionnifGetDeviceList returns a list of information describing each device on the link. A linkis a group of fieldbus devices connected across a single wire pair with no interveningbridges. Before nifGetDeviceList returns the list of information, nifGetDeviceList

waits until the revision argument passed in differs from the live list revision number thefieldbus interface keeps to the specified link. The revision numbers the fieldbus interfacekeeps start at one, so if you pass in a zero for revision , you can forcenifGetDeviceList to immediately return the current device list. To usenifGetDeviceList most effectively, in subsequent calls to it, you should pass in therevision parameter output from the previous call to nifGetDeviceList . Using the



nifGetDeviceListContinued

revision parameter output from the previous call forces nifGetDeviceList to wait untilthe device list has actually changed before returning the list of information.

If a device on the bus is unresponsive, its entry in the device information list has the tagand device ID unknown device , but its address field is correct. Also, the flag bitNIF_DEVICE_NO_RESPONSE is set.

The device list includes devices in the fixed, temporary, and visitor address ranges.

If there are too few input buffers, nifGetDeviceList returns an error code, but thenumDevices parameter is set to the total number of devices available. In this case, thebuffers you pass in do not contain valid data, but the revision number is set to the correctvalue. If a device is an interface device, then the flag bit NIF_DEVICE_INTERFACE isset. You can abort a pending nifGetDeviceList call by closing the link descriptor onwhich the call was made.

nifDeviceInfo_t is defined as follows:

typedef struct {char deviceID[DEV_ID_SIZE + 1];char pdTag[TAG_SIZE + 1];uint8 nodeAddress;uint32 flags;

} nifDeviceInfo_t;


E_INVALID_DESCRIPTOR The link descriptor is invalid.

E_BUF_TOO_SMALL There are not enough buffers allocated. If youreceive this error, your input buffers do not containvalid data.




nifGetDeviceListContinued

E_OBSOLETE_DESC The input descriptor is no longer valid. It wasclosed before nifGetDeviceList completed.




nifGetInterfaceList

PurposeRead the list of interface names from the NI-FBUS configuration.

FormatnifError_t nifGetInterfaceList(nifDesc_t ud,

int16 *numIntf, nifInterfaceInfo_t *info)

Inputud A valid session descriptor.numIntf The number of buffers for interface information

reserved in info.

OutputnumIntf The actual number of names returned.info An array of structures containing the interface

name and device ID for each interface.

ContextNot applicable.

DescriptionnifGetInterfaceList returns the interface name and device ID of each fieldbusinterface in the NI-FBUS configuration. The numIntf parameter is an IN/OUT parameter.On input, it must contain the number of buffers that info allocates and points to, and onoutput it contains the total number of interface information entries available. If not enoughbuffers were allocated, or if the info buffer is NULL, NI-FBUS returns an error and doesnot copy any data to the buffers. In this case, the numIntf parameter is still valid.

The nifInterfaceInfo_t structure is defined as follows:

typedef struct nifInterfaceInfo_t{char interfaceName[NIF_NAME_LEN];char deviceID[DEV_ID_SIZE +1];

} nifInterfaceInfo_t;



nifGetInterfaceListContinued

Note: nifGetInterfaceList is an internal function for NI-FBUS and doesnot cause fieldbus activity.


E_BUF_TOO_SMALL The buffer does not contain enough entries to holdall the interface information.

E_CONFIG_ERROR Some configuration information, such as registryinformation or network configuration information,is incorrect.



nifGetVFDList

PurposeGather VFD information on a specified physical device.

FormatnifError_t nifGetVFDList(nifDesc_t ud, nifVFDInfo_t *info,

uint16 *numBuffers)

Inputud The descriptor of the physical device to get the

VFD list for.numBuffers The number of buffers allocated in the info list.

OutputnumBuffers The number of VFDs actually in the device.info The VFD information.

ContextPhysical device.

DescriptionnifGetVFDList gathers function block application VFD information from the specifiedphysical device. A physical device is a fieldbus entity residing at a single address on a link.

If there are too few input buffers, or if the input buffer pointer is NULL, an error code isreturned, but the numBuffers parameter is set to the total number of VFDs in the device.In this case, no buffers contain valid data on output.



nifGetVFDListContinued

The info parameter has the following format:

typedef struct {char vfdTag[TAG_SIZE + 1];char vendor[TAG_SIZE +1];char model[TAG_SIZE +1];char revision[TAG_SIZE +1];int16 ODVersion;uint16 numTransducerBlocks;uint16 numFunctionBlocks;uint16 numActionObjects;uint16 numLinkObjects;uint16 numAlertObjects;uint16 numTrendObjects;uint16 numDomainObjects;uint16 totalObjects;uint32 flags;

} nifVFDInfo_t;



E_INVALID_DESCRIPTOR The input descriptor does not correspond to aphysical device.

E_BUF_TOO_SMALL There were not enough allocated buffers. Yourspecified input buffers do not contain valid data.

E_SM_NOT_OPERATIONAL The device is present, but cannot respond becauseit is at a default address.

E_OBSOLETE_DESC The input descriptor is no longer valid. It wasclosed before nifGetVFDList completed.





nifOpenBlock

PurposeReturn a descriptor representing a block.

FormatnifError_t nifOpenBlock (nifDesc_t ud, char *blockTag,

nifDesc_t *out_ud)

nifError_t nifOpenBlock (nifDesc_t ud, NIFB_ORDINAL(n),nifDesc_t *out_ud)

Inputud A valid session, link, physical device, or VFD

descriptor.blockTag The tag of the block. To access a block by ordinal

number within a VFD, use the NIFB_ORDINAL

macro in the nifbus.h header file. You can onlyaccess a block by ordinal number for VFDdescriptors.

Outputout_ud A descriptor for the block you request.

ContextVFD, physical device, link, session.

DescriptionnifOpenBlock returns a descriptor for the block you specify. You must pass a validsession, link, physical device, or VFD descriptor to this function.

There are two ways to specify the block: by tag, and by ordinal number. To open the blockby its tag, you must set blockTag to the current tag of the block. NI-FBUS returns an errorif it finds more than one block with the same tag. You can obtain the list of block tagswithin a specified VFD with a call to nifGetBlockList .



nifOpenBlockContinued

To open the block by its ordinal number, use the NIFB_ORDINAL macro. This macro isonly valid if ud is a VFD descriptor. The first block in a VFD has the ordinal number zero.Notice that the first block in a VFD is always the resource block.


E_INVALID_DESCRIPTOR The input descriptor is invalid.

E_MULTIPLE There are identical block tags.

E_ORDINAL_NUM_OUT_OF The ordinal number is out of the device’s range._RANGE

E_COMM_ERROR An error occurred when NI-FBUS communicatedwith the device.

E_NOT_FOUND There is no such block in the device or VFD withthe specified tag.

E_OBSOLETE_DESC The input descriptor is no longer valid. It wasclosed before nifOpenBlock completed.






nifOpenLink

PurposeReturn a descriptor representing a fieldbus link.

FormatnifError_t nifOpenLink (nifDesc_t session, uint8 interfaceOrDevID,

char *name, uint16 linkID, nifDesc_t *out_ud)

Inputsession A valid session descriptor on which to open the

link.interfaceOrDevID How to specify the link: zero if by interface name,

one if by local device ID.name The interface name or local device ID.linkID The link ID.

Outputout_ud A descriptor for the link you request.

ContextSession.

DescriptionnifOpenLink returns a descriptor for the link you specify. You must pass a valid sessiondescriptor to this function.

There are two ways you can specify the link. If the interfaceOrDevID parameter is zero,then name specifies the name of the interface the link is connected to. The list of validinterface names is contained in a configuration source which NI-FBUS has access to, andcan be obtained by a call to nifGetInterfaceList . If interfaceOrDevID is one, thenthe name specifies the device ID of an interface device to which NI-FBUS is attached.

In both cases, linkID is the fieldbus link ID number for the specified link. Forsingle-segment fieldbus networks, you can set linkID to zero.



nifOpenLinkContinued




E_NOT_FOUND The interface name, device ID or link ID youspecified is not found.


E_BAD_ARGUMENT The interfaceOrDevID value is not valid.

E_OBSOLETE_DESC The input descriptor is no longer valid. It wasclosed before nifOpenLink completed.




nifOpenPhysicalDevice

PurposeReturn a descriptor representing a physical device.

FormatnifError_t nifOpenPhysicalDevice (nifDesc_t ud, uint8 tagOrDevID,

char *name, nifDesc_t *out_ud)

Inputud A valid session or link descriptor on which to open

the device.tagOrDevID How to specify the device: zero if by physical

device tag, one if by device ID.name The tag or device ID.

Outputout_ud A descriptor for the device you request

ContextLink, session.

DescriptionnifOpenPhysicalDevice returns a descriptor for the physical device you specify. Youmust pass a valid session or link descriptor to this function. If you pass a link descriptor,NI-FBUS searches only that link for the specified device.

There are two ways you can specify the device. If the tagOrDevID parameter is zero, thenthe name specifies the tag of the physical device. If tagOrDevID is one, then name is thedevice ID of the device you specify. You can obtain the list of physical device tags anddevice IDs of devices on the network with a call to nifGetDeviceList .





nifOpenPhysicalDeviceContinued

E_BAD_ARGUMENT The tagOrDevID value is not valid.

E_NOT_FOUND No attached physical device has the specifieddevice ID or physical device tag.

E_MULTIPLE There is more than one device with the same tag ordevice ID on the same fieldbus network.



E_OBSOLETE_DESC The input descriptor is no longer valid. It wasclosed before nifOpenPhysicalDevice

completed.




nifOpenSession

PurposeReturn a descriptor for an NI-FBUS session.

FormatnifError_t nifOpenSession (void *reserved, nifDesc_t *out_ud)

Inputreserved Reserved for future use; you must set this value to

NULL.

Outputout_ud A descriptor for the NI-FBUS communications

entity you request.

Context

Not applicable.

DescriptionnifOpenSession returns a descriptor for the NI-FBUS session. When you open a session,NI-FBUS establishes a communication channel between your application and the NI-FBUSentity. All subsequent descriptors you open are associated with this session, and all theNI-FBUS calls on these descriptors communicate with the NI-FBUS entity through thecommunication channel established during the nifOpenSession call.

The reserved argument is reserved for future use; you must set reserved to NULL.


E_SERVER_NOT_RESPONDING Either the NI-FBUS server has not been started, orthe server, in its current state, cannot respond tothe request.



nifOpenSessionContinued

E_RESOURCES A system resource problem occurred. The resourceproblem is usually a memory shortage, or a failureof file access functions.



nifOpenVfd

PurposeReturn a descriptor representing a Virtual Field Device (VFD).

FormatnifError_t nifOpenVfd (nifDesc_t ud, char *vfdTag,

nifDesc_t *out_ud)

nifError_t nifOpenVfd (nifDesc_t ud, NIFB_ORDINAL(n),nifDesc_t *out_ud)

Inputud A valid physical device descriptor.vfdTag The tag of the VFD. To access by ordinal number

within a physical device, use the ORDINAL macroin the nifbus.h header file.

Outputout_ud A descriptor for the VFD you request

ContextPhysical device.

DescriptionnifOpenVfd returns a descriptor for the Virtual Field Device (VFD) you specify. A VFDis defined as a logical device within a physical device. More than one VFD can residewithin a physical device. You must pass a valid physical device descriptor to this function.

There are two ways to specify the VFD: by tag, and by ordinal number. To open the VFDby its tag, you must set the vfdTag parameter to the current tag of the VFD. NI-FBUSreturns an error if it finds more than one VFD with the same tag. You can obtain the list ofVFD tags within a specified physical device with a call to nifGetVFDList .

To open the VFD by its ordinal number, use the NIFB_ORDINAL macro. The first VFD ofyour application in a physical device has the ordinal number zero. Notice that theManagement VFDs are not included in the ordinal numbering scheme.



nifOpenVfdContinued



E_MULTIPLE There are identical VFD tags.



E_NOT_FOUND No VFD in the device has the specified VFD tag.



E_OBSOLETE_DESC The input descriptor is no longer valid. It wasclosed before nifOpenVfd completed.




Core Fieldbus Functions2

Chapter

This chapter lists and describes the core NI-FBUS functions.

You can use the NI-FBUS core functions to access fieldbus block parameters using anytype of descriptor. Because there are several ways to identify the fieldbus block parameters,the NI-FBUS core functions accept special interface macros for the name argument, as wellas the standard TAG.PARAM identifier format. Refer to the Using Interface Macros sectionat the end of this chapter for tips on using the interface macros.

For an explanation of the format of this chapter, refer to Format of the FunctionInformation section in Chapter 1, Administrative Functions.

Table 2-1. List of Core Functions

Function Purpose

nifFreeObjectAttributes Free an nifAttributes_t structure allocatedduring a previous call tonifGetObjectAttributes

nifGetObjectAttributes Read a single set of object attributes from theDevice Description (DD)

nifGetObjectSize Return the size in bytes of an object’s value

nifGetObjectType Returns the Object Dictionary type of thespecified object.

nifReadObject Read an object’s value from a device

nifWriteObject Write a parameter value to a device

Chapter 2 Core Fieldbus Functions


nifFreeObjectAttributes

PurposeFree an nifAttributes_t structure allocated during a previous call tonifGetObjectAttributes .

FormatnifError_t nifFreeObjectAttributes(nifAttributes_t *attr)

Inputattr Object attribute values your application reads using

nifGetObjectAttributes .


ContextSession, block, VFD, physical device, link.

DescriptionnifFreeObjectAttributes frees up the memory associated with thenifAttributes_t structure specified by attr . attr must have been filled in by asuccessful call to nifGetObjectAttributes . Once this function has been called, thecontents of attr are no longer valid.

If your application does not call this function after calling nifGetObjectAttributes ,your application will not free up memory properly.


E_BAD_ARGUMENT attr was not a valid nifAttributes_t

structure.



nifGetObjectAttributes

PurposeRead a single set of object attributes from the Device Description (DD).

FormatnifError_t nifGetObjectAttributes(nifDesc_t ud, char *name,

nifAttributes_t *attr)

nifError_t nifGetObjectAttributes(nifDesc_t ud,NIFB_INDEX(uint16 idx), nifAttributes_t *attr)

nifError_t nifGetObjectAttributes(nifDesc_t ud,NIFB_INDEX_SUBINDEX(uint16 idx, uint16 subidx),nifAttributes_t *attr)

nifError_t nifGetObjectAttributes(nifDesc_t ud,NIFB_ITEM(uint32 item), nifAttributes_t *attr)

nifError_t nifGetObjectAttributes(nifDesc_t ud,NIFB_ITEM_SUBINDEX(uint32 item, uint16 subidx),nifAttributes_t *attr)

nifError_t nifGetObjectAttributes(nifDesc_t ud,NIFB_BLOCK_ITEM(char *blocktag, uint32 item),nifAttributes_t *attr)

nifError_t nifGetObjectAttributes(nifDesc_t ud,NIFB_BLOCK_ITEM_SUBINDEX(char *blocktag, uint32 item,uint16 subidx), nifAttributes_t *attr)

nifError_t nifGetObjectAttributes(nifDesc_t ud,NIFB_BLOCK_INDEX(char *blocktag, uint16 idx),nifAttributes_t *attr)

nifError_t nifGetObjectAttributes(nifDesc_t ud,NIFB_BLOCK_INDEX_SUBINDEX(char *blocktag, uint16 idx,uint16 subidx), nifAttributes_t *attr)

nifError_t nifGetObjectAttributes(nifDesc_t ud,NIFB_NAME_SUBINDEX(char *name, uint16 subidx),nifAttributes_t *attr)



nifGetObjectAttributesContinued

nifError_t nifGetObjectAttributes(nifDesc_t ud,NIFB_BLOCK_NAME_SUBINDEX(char *blocktag, char *name,uint16 subidx), nifAttributes_t *attr)

Inputud The descriptor (of any type if by name; VFD or

block if by index).name Name of the object you need the DD attributes of,

in BLOCKTAG.PARAM form. To specify a structureelement by name, specify the name inBLOCKTAG.STRUCT.ELEMENT format. Refer toTable 2-4, Core Function Macros, at the end ofthis chapter for an explanation of how to usemacros to specify the object.

Note: Any index specified is the OD index, the same index that would be usedin an nifReadObject call.

Outputattr Object attribute values read from the DDOD

(Device Description Object Dictionary). The typenifAttributes_t consists of a data structureincluding a type code which selects from a list ofstructures, one for each type of object. Otherinformation, including whether individualattributes were successfully evaluated and whetherindividual attributes are dynamic (meaning theycould change) is also provided. The structure is toolong to be included in this manual, so you can findit in the NI-FBUS header files.





DescriptionNI-FBUS reads the DD object attributes identified in the call from the DDOD associatedwith ud and returned in attr . Notice that the object attributes describe certain

characteristics of the object, but do not contain the object’s value. The DD object attributesalso differ in content from the FMS OD Object Description of the object.

For block, VFD, physical device, or link descriptors, the object name may refer to avariable or a variable list. You would normally use nifGetObjectAttributes to readthe type description of a certain data type.

Refer to Table 2-4, Core Function Macros, at the end of this chapter for an explanation ofhow to use macros to specify the object.

For more detailed information concerning the nifAttributes_t structure, refer to theFieldbus Foundation Device Description Services User Guide, Chapter 3, Usingddi_get_item.

Note: After a successful call to nifGetObjectAttributes , your applicationmust call nifFreeObjectAttributes when it is done using the attr

structure. Your application will not free up memory correctly if it doesnot perform this operation.



E_INVALID_DESCRIPTOR The device descriptor does not correspond to aVFD or block

E_SYMBOL_FILE_NOT_FOUND NI-FBUS could not find the symbol file.

E_DEVICE_NOT_PRESENT The requested device is not operational.




E_NOT_FOUND The referred object does not exist, or it does nothave object attributes.

E_MULTIPLE NI-FBUS found more than one identical tag; thefunction failed.


E_OBSOLETE_DESC The input descriptor is no longer valid. It wasclosed before nifGetObjectAttributes

completed.




nifGetObjectSize

PurposeReturn the size in bytes of an object’s value.

FormatnifError_t nifGetObjectSize(nifDesc_t ud, char *name,

int16 *size_in_bytes)

nifError_t nifGetObjectSize(nifDesc_t ud, NIFB_INDEX(uint16 idx),int16 *size_in_bytes)

nifError_t nifGetObjectSize(nifDesc_t ud,NIFB_INDEX_SUBINDEX(uint16 idx, uint16 subidx),int16 *size_in_bytes)

nifError_t nifGetObjectSize(nifDesc_t ud,NIFB_ITEM(uint32 item), int16 *size_in_bytes)

nifError_t nifGetObjectSize(nifDesc_t ud,NIFB_ITEM_SUBINDEX(uint32 item, uint16 subidx),int16 *size_in_bytes)

nifError_t nifGetObjectSize(nifDesc_t ud,NIFB_BLOCK_ITEM(char *blocktag, uint32 item),int16 *size_in_bytes)

nifError_t nifGetObjectSize(nifDesc_t ud,NIFB_BLOCK_ITEM_SUBINDEX(char *blocktag, uint32 item,uint16 subidx), int16 *size_in_bytes)

nifError_t nifGetObjectSize(nifDesc_t ud,NIFB_BLOCK_INDEX(char *blocktag, uint16 idx),int16 *size_in_bytes)

nifError_t nifGetObjectSize(nifDesc_t ud,NIFB_BLOCK_INDEX_SUBINDEX(char *blocktag, uint16 idx,uint16 subidx), int16 *size_in_bytes)

nifError_t nifGetObjectSize(nifDesc_t ud,NIFB_NAME_SUBINDEX(char *name, uint16 subidx),int16 *size_in_bytes)



nifGetObjectSizeContinued

nifError_t nifGetObjectSize(nifDesc_t ud,NIFB_BLOCK_NAME_SUBINDEX(char *blocktag, char *name,uint16 subidx), int16 *size_in_bytes)

Inputud The descriptor (of any type if by name, or of a

block or VFD if by index).name Character string name of the object you need the

size of, in BLOCKTAG.PARAM form. To specify astructure element by name, specify the name inBLOCKTAG.STRUCT.ELEMENT format. Refer toTable 2-4, Core Function Macros, at the end ofthis chapter for an explanation of how to usemacros to specify the character string name.

Outputsize_in_bytes The size of the object.


DescriptionThis function returns the size of the specified Object Value. You have to pass a buffer ofthe returned size to nifReadObject to hold the value of the object.

Refer to Table 2-4, Core Function Macros, at the end of this chapter for an explanation ofhow to use macros to specify the character string name.


E_INVALID_DESCRIPTOR The specified descriptor is invalid.


E_NOT_FOUND The named object does not exist.



nifGetObjectSizeContinued

E_MULTIPLE Multiple identical tags were found; the functionfailed.

E_OBSOLETE_DESC The input descriptor is no longer valid. It wasclosed before nifGetObjectSize completed.





nifGetObjectType

PurposeReturns the Object Dictionary type of the specified object.

FormatnifError_t nifGetObjectType(nifDesc_t ud, char *objName,

nifObjTypeList_t *typeData)

nifError_t nifGetObjectType(nifDesc_t ud,NIFB_INDEX(uint16 idx), nifObjTypeList_t *typeData)

nifError_t nifGetObjectType(nifDesc_t ud,NIFB_INDEX_SUBINDEX(uint16 idx, uint16 subidx),nifObjTypeList_t *typeData)

nifError_t nifGetObjectType(nifDesc_t ud,NIFB_ITEM(uint32 item), nifObjTypeList_t *typeData)

nifError_t nifGetObjectType(nifDesc_t ud,NIFB_ITEM_SUBINDEX(uint32 item, uint16 subidx),nifObjTypeList_t *typeData)

nifError_t nifGetObjectType(nifDesc_t ud,NIFB_BLOCK_ITEM(char *blocktag, uint32 item),nifObjTypeList_t *typeData)

nifError_t nifGetObjectType(nifDesc_t ud,NIFB_BLOCK_ITEM_SUBINDEX(char *blocktag, uint32 item,uint16 subidx), nifObjTypeList_t *typeData)

nifError_t nifGetObjectType(nifDesc_t ud,NIFB_BLOCK_INDEX(char *blocktag, uint16 idx),nifObjTypeList_t *typeData)

nifError_t nifGetObjectType(nifDesc_t ud,NIFB_BLOCK_INDEX_SUBINDEX(char *blocktag, uint16 idx,uint16 subidx), nifObjTypeList_t *typeData)

nifError_t nifGetObjectType(nifDesc_t ud,NIFB_NAME_SUBINDEX(char *name, uint16 subidx),nifObjTypeList_t *typeData)



nifGetObjectTypeContinued

nifError_t nifGetObjectType(nifDesc_t ud,NIFB_BLOCK_NAME_SUBINDEX(char *blocktag, char *name,uint16 subidx), nifObjTypeList_t *typeData)

Inputud The descriptor of the session, link, physical device,

VFD or block if you are accessing by name. If youare accessing by index, ud must be a VFD orblock.

objName The name of the parameter you want to read theOD type of, in BLOCKTAG.PARAM form. Refer toTable 2-4, Core Function Macros, at the end ofthis chapter for an explanation of how to usemacros to specify the parameter. To specify anamed structure element, supply name inBLOCKTAG.STRUCT.ELEMENT format. To specifya type index returned by a previous call tonifGetObjectType , use the NIFB_TYPE_INDEX

macro.

OutputtypeData Object Type value read from the object dictionary

in the device. The nifObjTypeList_t datastructure is a record consisting of an object typecode, the number of elements, and a pointer to alist of elements of type nifObjElem_t . ThenifObjElem_t type is a structure which consistsof two elements: the OD typeIndex of theelement and the OD length of the element.

ContextSession, block, VFD, DDOD, physical device, link.




DescriptionnifGetObjectType is used to read the Object Dictionary type values of objects such asblock parameters, MIB objects or communication parameters from devices.

• If ud is the descriptor of a link, then objName must be in BLOCKTAG.PARAM_NAMEformat.

• If ud is a session descriptor, then all links are searched for the givenBLOCKTAG.PARAM_NAME. The call fails if identical BLOCKTAG.PARAM_NAME tags arefound on the bus. Index access is not allowed for session descriptors.

• If ud is the descriptor of a general function block application VFD, and you use theNIFB_INDEX macro, the index specified is the index of the object in the VFD.

• If ud is the descriptor of a function block, name must be in PARAM_NAME format.

• If ud is the descriptor of a function block, and you use the NIFB_INDEX orNIFB_INDEX_SUBINDEX macro, the index specified is the relative index of theparameter within the block. Relative indices start at one for the first parameter. Indexzero retrieves the OD type of the block itself.

• In all cases, you can expand PARAM_NAME to STRUCT.ELEMENT format to represent anamed element of a named structure.

Refer to Table 2-4, Core Function Macros, at the end of this chapter for an explanation ofhow to use macros to specify the parameter.

The nifObjTypeList_t data structure is defined as follows:

typedef struct {uint8 objectCode;uint16 numElems;char blockTag[TAG_SIZE + 1];nifObjElem_t *allElems;} nifObjTypeList_t;

The nifObjElem_t data type is defined as follows:

typedef struct {uint16 objTypeIndex;uint16 objSize;} nifObjElem_t;




The objectCode returned in the data structure nifObjTypeList_t is as specified in theFMS Specifications in the Fieldbus Foundation Specifications, and is listed in Table 2-2 foryour convenience.

Table 2-2. Object Codes for the nifObjTypeList_t Data Structure

ObjectObject Code

in fbtypes.h

Domain ODT_DOMAIN

Program Invocation ODT_PI

Event ODT_EVENT

Data Type ODT_SIMPLETYPE

Data Type

Structure

Description

ODT_STRUCTTYPE

Simple Variable ODT_SIMPLEVAR

Array ODT_ARRAY

Record ODT_RECORD

Variable List ODT_VARLIST

For object codes ODT_STRUCTTYPE, ODT_SIMPLEVAR, ODT_ARRAY, and ODT_RECORD, thelist of elements in allElements contains the typeIndex and the size of each componentelement. For example, the following fragment of pseudocode gets the type information fora structured object and does something with the type information for each element:

nifObjTypeList_t typeInfo;nifDesc_t aiBlock;int loop;

...




nifGetObjectType(aiBlock, "OUT", &typeInfo);for (loop=0; loop < typeInfo.numElems; loop++){

doSomethingWithElement(typeInfo.allElems[loop]);}

For variable list objects (type ODT_VARLIST), you must call nifGetObjectType for eachelement in the list of elements with the typeIndex of the element returned in the list withthe first nifGetObjectType call. The typeIndex of the element returned in the list inthis case is the relative index of the element within the block, whose name is returned byblockTag . These subsequent calls to nifGetObjectType should use the NIFB_INDEX

macro to specify the typeIndex returned by the first call.

For example, the following fragment of pseudocode gets the type information for a variablelist object and does something with the type information for each variable:

nifObjTypeList_t typeInfo, varTypeInfo;nifDesc_t aiBlock;int loop;

...

nifGetObjectType(aiBlock, "VIEW_1", &typeInfo);if (typeinfo.objectCode == ODT_VARLIST){

for (loop=0; loop < typeInfo.numElems; loop++){

nifGetObjectType(aiBlock,NIFB_INDEX(typeInfo.allElems[loop].objTypeIndex),&varTypeInfo);

doSomethingWithVariable(varTypeInfo);}

}

For all successful calls to nifGetObjectType , you must call nifFreeGetObjectType

to clean up memory allocated within these structures.




For objects with the object codes ODT_DOMAIN, ODT_PI, ODT_EVENT, andODT_SIMPLETYPE, only the object type is returned, and the list of elements allElems inthe structure nifObjTypeList_t is empty. The list of standard data types for an objectwhich has the object code ODT_SIMPLETYPE is also as specified in the FMS Specificationsin the Fieldbus Foundation Specifications and is listed in Table 2-3 for your convenience.

Table 2-3. Standard Data Types for Objects with the Object Code ODT_SIMPLETYPE

Data TypeobjTypeIndexin fbtypes.h

Number ofOctets (Size)

Boolean FF_BOOLEAN 1

Integer8 FF_INTEGER8 1



Unsigned8 FF_UNSIGNED8 1



Floating Point FF_FLOAT 4

Visible String FF_VISIBLE_STRING 1, 2, 3,...

Octet String FF_OCTET_STRING 1, 2, 3,...

Date FF_DATE 7

Time of Day FF_TIMEOFDAY 4 or 6

Time Difference FF_TIME_DIFF 4 or 6

Bit String FF_BIT_STRING 1, 2, 3,...

Time Value FF_TIME_VALUE 8


E_INVALID_DESCRIPTOR The descriptor you specified is not valid.




E_TIMEOUT The device containing the object is present but didnot respond within the timeout period.

E_MULTIPLE More than one identical tag was found; thefunction failed.

E_NOT_FOUND NI-FBUS could not fine the specified object.

E_BAD_ARGUMENT The object specified by index was that of a simpledata type, which must already be known to you.

E_RESOURCES NI-FBUS is unable to allocate some systemresource; this is usually a memory problem.

E_SERVER_CONNECTION_LOST The session established with NI-FBUS, underwhich the descriptor was opened, has been lost orclosed.



nifReadObject

PurposeRead an object’s value from a device.

FormatnifError_t nifReadObject(nifDesc_t ud, char *name, void *buffer,

uint8 *length)

nifError_t nifReadObject(nifDesc_t ud, NIFB_INDEX(uint16 idx),void *buffer, uint8 *length)

nifError_t nifReadObject(nifDesc_t ud,NIFB_INDEX_SUBINDEX(uint16 idx, uint16 subidx),void *buffer, uint8 *length)

nifError_t nifReadObject(nifDesc_t ud,NIFB_ITEM(uint32 item), void *buffer, uint8 *length)

nifError_t nifReadObject(nifDesc_t ud,NIFB_ITEM_SUBINDEX(uint32 item, uint16 subidx),void *buffer, uint8 *length)

nifError_t nifReadObject(nifDesc_t ud,NIFB_BLOCK_ITEM(char *blocktag, uint32 item),void *buffer, uint8 *length)

nifError_t nifReadObject(nifDesc_t ud,NIFB_BLOCK_ITEM_SUBINDEX(char *blocktag, uint32 item,uint16 subidx), void *buffer, uint8 *length)

nifError_t nifReadObject(nifDesc_t ud,NIFB_BLOCK_INDEX(char *blocktag, uint16 idx),void *buffer, uint8 *length)

nifError_t nifReadObject(nifDesc_t ud,NIFB_BLOCK_INDEX_SUBINDEX(char *blocktag, uint16 idx,uint16 subidx), void *buffer, uint8 *length)

nifError_t nifReadObject(nifDesc_t ud,NIFB_NAME_SUBINDEX(char *name, uint16 subidx),void *buffer, uint8 *length)



nifReadObjectContinued

nifError_t nifReadObject(nifDesc_t ud,NIFB_BLOCK_NAME_SUBINDEX(char *blocktag, char *name,uint16 subidx), void *buffer, uint8 *length)


VFD or block if reading by name. If reading byindex, ud must be a VFD or block.

name Name of the parameter your application reads, inBLOCKTAG.PARAM format. To specify a structureelement by name, specify the name inBLOCKTAG.STRUCT.ELEMENT format. Refer toTable 2-4, Core Function Macros, at the end ofthis chapter for an explanation of how to usemacros to specify the parameter.

length The size of the buffer to hold the result, in bytes.

Outputbuffer The value that NI-FBUS reads.length The actual size of the resulting data, in bytes.


DescriptionnifReadObject reads the values of objects such as block parameters or communicationsparameters from devices.

• If ud is the descriptor of a link, then name must be in the formatBLOCKTAG.PARAM_NAME.

• If ud is a session descriptor, then all links are searched for the givenBLOCKTAG.PARAM_NAME. The call fails if multiple identical BLOCKTAG.PARAM_NAMEtags are located on the bus. Index access is not allowed for session descriptors.

• If ud is the descriptor of a general function block application VFD, then name must bein the format BLOCKTAG.PARAM_NAME.




• If ud is the descriptor of a function block, name must be in the format PARAM_NAME.

• If ud is the descriptor of a function block, and the NIFB_INDEX orNIFB_INDEX_SUBINDEX macro is used, the index specified is the relative index of theparameter within the block. Relative indices start at 1 for the first parameter.

• In all descriptor cases, you can expand PARAM_NAME itself to STRUCT.ELEMENTformat to represent a named element of a named structure.

In each case, name can represent either a variable or a variable list object. You shoulddetermine the size of the object beforehand, possibly with a call to nifGetObjectSize . Ifthe object is larger than the buffer size specified in length , NI-FBUS returns an error, andnone of the data in the buffer is valid.


The data nifReadObject returns is in Fieldbus Foundation FMS Application format. Youmust accomplish conversion of the data to the internal format of your processor andcompiler.


E_INVALID_DESCRIPTOR The descriptor does not correspond to a VFDor function block; this descriptor is no longer valid.

E_NOT_FOUND The referred object does not exist.

E_OBJECT_ACCESS_DENIED The NI-FBUS interface does not have the requiredprivileges. The access group you belong to is notallowed to acknowledge the event, or the passwordyou used is wrong.


E_BUF_TOO_SMALL The object is larger than your buffer.






E_OBSOLETE_DESC The input descriptor is no longer valid. It wasclosed before nifReadObject completed.


E_PARAMETER_CHECK The device reported a violation ofparameter-specific checks.




nifWriteObject

PurposeWrite a parameter value to a device.

FormatnifError_t nifWriteObject(nifDesc_t ud, char *name, void *buffer,

uint8 length)

nifError_t nifWriteObject(nifDesc_t ud, NIFB_INDEX(uint16 idx),void *buffer, uint8 length)

nifError_t nifWriteObject(nifDesc_t ud,NIFB_INDEX_SUBINDEX(uint16 idx, uint16 subidx),void *buffer, uint8 length)

nifError_t nifWriteObject(nifDesc_t ud,NIFB_ITEM(uint32 item), void *buffer, uint8 *length)

nifError_t nifWriteObject(nifDesc_t ud,NIFB_ITEM_SUBINDEX(uint32 item, uint16 subidx),void *buffer, uint8 *length)

nifError_t nifWriteObject(nifDesc_t ud,NIFB_BLOCK_ITEM(char *blocktag, uint32 item),void *buffer, uint8 *length)

nifError_t nifWriteObject(nifDesc_t ud,NIFB_BLOCK_ITEM_SUBINDEX(char *blocktag, uint32 item,uint16 subidx), void *buffer, uint8 *length)

nifError_t nifWriteObject(nifDesc_t ud,NIFB_BLOCK_INDEX(char *blocktag, uint16 idx),void *buffer, uint8 *length)

nifError_t nifWriteObject(nifDesc_t ud,NIFB_BLOCK_INDEX_SUBINDEX(char *blocktag, uint16 idx,uint16 subidx), void *buffer, uint8 *length)

nifError_t nifWriteObject(nifDesc_t ud,NIFB_NAME_SUBINDEX(char *name, uint16 subidx),void *buffer, uint8 *length)



nifWriteObjectContinued

nifError_t nifWriteObject(nifDesc_t ud,NIFB_BLOCK_NAME_SUBINDEX(char *blocktag, char *name,uint16 subidx), void *buffer, uint8 *length)


VFD or block if writing by name. If writing byindex, ud must be a VFD or block.

name Name of the parameter you want NI-FBUS towrite, in BLOCKTAG.PARAM form. To specify astructure element by name, specify the name inBLOCKTAG.STRUCT.ELEMENT format. Refer toTable 2-4, Core Function Macros, at the end ofthis chapter for an explanation of how to usemacros to specify the parameter.

buffer The value you want NI-FBUS to write.length The size of the data buffer, in bytes.



DescriptionnifWriteObject writes the values of a function block parameter to a device.

• If ud is the descriptor of a session or link, then name must be in the formatBLOCKTAG.PARAM_NAME.

• If ud is a session descriptor, then all links are searched for the givenBLOCKTAG.PARAM_NAME. The function fails if more than one identicalBLOCKTAG.PARAM_NAME match is found.

• If ud is a physical device descriptor, a parameter is written byBLOCKTAG.PARAM_NAME.

• If ud is the descriptor of a general Virtual Field Device, then name must be in theformat BLOCKTAG.PARAM_NAME.




• If ud is the descriptor of a function block, name must be in the format PARAM_NAME.

• If ud is the descriptor of a function block, and you use the NIFB_INDEX orNIFB_INDEX_SUBINDEX macro, the index specified is the relative index of theparameter within the block. Relative indices start at one for the first parameter.

• In all descriptor cases, you can expand PARAM_NAME itself to STRUCT.ELEMENTformat to represent a named element of a named structure.



E_INVALID_DESCRIPTOR The device descriptor does not correspond to aVFD.


E_ORDINAL_NUM_OUT_OF The parameter is out of the device’s range._RANGE

E_OBJECT_ACCESS The device does not support write access to this_UNSUPPORTED object.




E_PARAMETER_CHECK The device reported a violation ofparameter-specific checks.

E_EXCEED_LIMIT The device reported that the value exceeds thelimit.




E_WRONG_MODE_FOR The device reported that the current function_REQUEST block mode does not allow you to write to the

parameter.

E_WRITE_IS_PROHIBITED The device reported that the WRITE_LOCK

parameter value is set. The WRITE_LOCK parameterprohibits writing to the name parameter.

E_DATA_NEVER_WRITABLE The specified object is read-only.




Using Interface MacrosThis section contains tips for using the NI-FBUS interface macros. These macros aredefined in the header file nifbus.h .

Table 2-4. Core Function Macros

Descriptor TypeYou Have

Parameter InformationYou Have Macro to Use

Block Descriptor Name Normal Access by Name

Block Descriptor Name and Subindex NIFB_NAME_SUBINDEX

Block Descriptor Relative Index within the BlockNIFB_INDEX

Block Descriptor Relative Index and Subindex NIFB_INDEX_SUBINDEX

Block Descriptor DD Item ID NIFB_ITEM

Block Descriptor DD Item ID and Subindex NIFB_ITEM_SUBINDEX

Non-Block Descriptor Name Normal Access UsingBLOCKTAG.PARAM Format

Non-Block Descriptor Name and Subindex NIFB_BLOCK_NAME_SUBINDEX

Non-Block Descriptor Relative Index within the BlockNIFB_BLOCK_INDEX

Non-Block Descriptor Relative Index and Subindex NIFB_BLOCK_INDEX_SUBINDEX

Non-Block Descriptor DD Item ID NIFB_BLOCK_ITEM

Non-Block Descriptor DD Item ID and Subindex NIFB_BLOCK_ITEM_SUBINDEX

As shown in Table 2-4, you can specify the parameter your application reads in the name

parameter in many different ways.

• To specify an object by index, use the NIFB_INDEX macro in the nifbus.h headerfile.

• To specify an array or structure element by index and subindex, use theNIFB_INDEX_SUBINDEX macro.

• If you already have a block descriptor, you can specify an object by its item ID withthe NIFB_ITEM macro, or you can specify a subelement by its item ID with theNIFB_ITEM_SUBINDEX macro.

• If you do not have a block descriptor, you have the following choices:

– You can use the NIFB_BLOCK_ITEM macro to specify an item.



– You can use the NIFB_BLOCK_ITEM_SUBINDEX macro to specify a subelement.

– You can use the NIFB_BLOCK_INDEX macro specify an object by index.

– You can use the NIFB_BLOCK_INDEX_SUBINDEX macro to specify a subindex.

• You can find all these macros in the nifbus.h header file


Alert and Trend Functions3

Chapter

This chapter lists and describes the NI-FBUS alert and trend functions.

For an explanation of the format of this chapter, refer to Format of the FunctionInformation section in Chapter 1, Administrative Functions.

Table 3-1. List of Alert Functions

Function Purpose

nifAcknowledgeAlarm Acknowledge an alarm received

nifWaitAlert Wait for an alert (an event or an alarm) from aspecific device or from any device

Table 3-2. Trend Function

Function Purpose

nifWaitTrend Wait for a trend from a specific device or fromany device

Chapter 3 Alert and Trend Functions


nifAcknowledgeAlarm

PurposeAcknowledge an alarm received.

FormatnifError_t nifAcknowledgeAlarm(nifDesc_t ud, char *alarmName)

Inputud A session, link, physical device, VFD, or block

descriptor for the alarmalarmName The name of the alarm object that you want

NI-FBUS to acknowledge. If ud is a blockdescriptor, alarmName should be the parametername, otherwise alarmName should be inBLOCKTAG.PARAMNAME format.


DescriptionnifAcknowledgeAlarm acknowledges an alarm notification from a device. NI-FBUSclears the unacknowledged field associated with the alarm object alarmName .

If ud is a block descriptor, the alarmName is the same as the alarmOrEventName field ofthe alert data you get in the nifWaitAlert call. If ud is a session, link, VFD, or physicaldevice descriptor, then alarmName is in BLOCKTAG.PARAMNAME format, where blockTag

is the same as the blockTag field of the alert data in the nifWaitAlert function.


E_INVALID_DESCRIPTOR The device descriptor is not a valid descriptor.

E_OBJECT_ACCESS_DENIED The NI-FBUS interface does not have the requiredprivileges. The access group you belong to is notallowed to acknowledge the event, or the passwordyou used is wrong.



nifAcknowledgeAlarmContinued

E_COMM_ERROR An error occurred when NI-FBUS tried tocommunicate with the device.

E_ALARM_ACKNOWLEDGED The alarm has already been acknowledged.

E_MULTIPLE There are identical block tags.

E_NOT_FOUND There is no such block in the device or VFD withthe specified tag.





nifWaitAlert

PurposeWait for an alert (an event or an alarm) from a specific device or from any device.

FormatnifError_t nifWaitAlert(nifDesc_t ud, nifAlertData_t *aldata,

uint8 alertPriority)


VFD, block, or link the alert comes from.alertPriority Lowest priority of the alert coming in that you

want to wait on.

Outputaldata The information about the specific alert.


Descriptionud represents a descriptor of a session, link, a physical device, a VFD, or a block. If ud is aVFD descriptor, then NI-FBUS waits for an alert from any block in the Virtual FieldDevice. If ud is a block, NI-FBUS waits for an alarm or event from the block ud refers to.If ud represents a link, nifWaitAlert completes when an event is received from anydevice connected to that link. If the descriptor is a session descriptor, the function waits onany event from any attached link.

nifWaitAlert waits indefinitely until NI-FBUS receives an alert with a priority greaterthan or equal to the input alert priority. Your application can have a dedicated thread whichdoes nifWaitAlert only.

When the NI-FBUS interface receives an alert, the aldata parameter is filled in with theinformation about the alert. The form of aldata->alertData depends on the value ofaldata->alertType . alData->alarmOrEventName is the name of the alarmparameter or event parameter that caused the alert. alData->deviceTag andalData->blockTag are the tags of the device and the block of the alarm, respectively.



nifWaitAlertContinued

nifWaitAlert sends a confirmation to the device, informing the alerting device that thealert was received. Note that this is a separate step from alert acknowledgment, which mustbe carried out for alarms using nifAcknowledgeAlarm .

If you have multiple threads waiting to receive the same alert, NI-FBUS sends a copy of thealert to all the waiting threads. Your application must ensure that only one threadacknowledges any one alarm with a call to nifAcknowledgeAlarm . You can abort apending nifWaitAlert call by closing the descriptor on which the call was made.

The alertType parameter can be ALERT_ANALOG, ALERT_DISCRETE, or ALERT_UPDATE.

nifAlertData_t is defined as follows:

typedef struct nifAlertData_t{uint8 alertType;char deviceTag[TAG_SIZE + 1];char blockTag[TAG_SIZE + 1];char alarmOrEventName [TAG_SIZE + 1];uint8 alertKey;uint8 standardType;uint8 mfrType;uint8 messageType;uint8 priority;nifTime_t timeStamp;uint16 subCode;uint16 unitIndex;union {

float floatAlarmData;uint8 discreteAlarmData;uint16 staticRevision;

} alertData;} nifAlertData_t ;


E_INVALID_DESCRIPTOR The descriptor you gave is invalid.



nifWaitAlertContinued

E_OBSOLETE_DESC The input descriptor is no longer valid. It wasclosed before nifWaitAlert completed.




nifWaitTrend

PurposeWait for a trend from a specific device or from any device.

FormatnifError_t nifWaitTrend(nifDesc_t ud, nifTrendData_t *trend)

Inputud The descriptor of the session, physical device,

VFD, block, or link that the trend comes from.

Outputtrend The information about the specific trend.


Descriptionud represents a descriptor of a session, link, physical device, VFD, or block. If ud is a VFDdescriptor, then NI-FBUS waits for a trend from any block in the Virtual Field Device. Ifud is a block, NI-FBUS waits for a trend from the block ud identifies. If ud represents alink, the call completes when a trend is received from any device connected to that link. Ifthe descriptor is a session descriptor, nifWaitTrend waits on any trend from any attachedlink.

nifWaitTrend waits indefinitely until the NI-FBUS interface receives a trend. Yourapplication can have a dedicated thread which does nifWaitTrend only.

When a trend comes in, the trend parameter is filled in with the information about thetrend. The form of trend->trendData depends on the value of trend->trendType .There are three trend types: TREND_FLOAT, TREND_DISCRETE and TREND_BITSTRING. Ifthe trend type is TREND_FLOAT, the trend->trendData is a 16-element array of floatingpoint numbers. If the trend type is TREND_DISCRETE, the trend->trendData is a16-element array of 1-byte integers. If the trend type is TREND_BITSTRING, thetrend->trendData is a 16-element array of 2-byte bit strings, which is equivalent to a32-element array of 1-byte integers. deviceTag and blockTag are the device and blocktags of the parameter that has the trend; paramName is the name of the parameter.



nifWaitTrendContinued

If you have multiple threads waiting to receive the same trend, NI-FBUS sends a copy ofthe trend to all the waiting threads. You can abort a pending nifWaitTrend call by closingthe descriptor on which the call was made.

The trend type can be TREND_FLOAT, TREND_DISCRETE, or TREND_BITSTRING. Thesample type can be SAMPLE_INSTANT or SAMPLE_AVERAGE.

nifTrendData_t is defined as follows:

typedef struct nifTrendData_t {uint8 trendType;char deviceTag[TAG_SIZE + 1];char blockTag[TAG_SIZE + 1];char paramName[TAG_SIZE + 1];uint8 sampleType;uint32 sampleInterval;nifTime_t lastUpdate;uint8 status[16];union {

float f[16];uint8 d[16];uint8 bs[32];

} trendData;} nifTrendData_t;


E_INVALID_DESCRIPTOR The descriptor you gave is not valid.


© National Instruments Corporation A-1 NI-FBUS FRM for Windows NT

Customer Communication

Appendix

For your convenience, this appendix contains forms to help you gather the information necessary tohelp us solve technical problems you might have as well as a form you can use to comment on theproduct documentation. Filling out a copy of the Technical Support Form before contactingNational Instruments helps us help you better and faster.

National Instruments provides comprehensive technical assistance around the world. In the U.S. andCanada, applications engineers are available Monday through Friday from 8:00 a.m. to 6:00 p.m.(central time). In other countries, contact the nearest branch office. You may fax questions to us atany time.

Electronic Services

Bulletin Board SupportNational Instruments has BBS and FTP sites dedicated for 24-hour support with a collection of filesand documents to answer most common customer questions. From these sites, you can alsodownload the latest instrument drivers, updates, and example programs. For recorded instructions onhow to use the bulletin board and FTP services and for BBS automated information, call(512) 795-6990. You can access these services at:

United States: (512) 794-5422Up to 14,400 baud, 8 data bits, 1 stop bit, no parity

United Kingdom: 01635 551422Up to 9,600 baud, 8 data bits, 1 stop bit, no parity

France: 1 48 65 15 59Up to 9,600 baud, 8 data bits, 1 stop bit, no parity

FTP SupportTo access our FTP site, log on to our Internet host, ftp.natinst.com , as anonymous and useyour Internet address, such as [email protected] , as your password. The support files anddocuments are located in the /support directories.

Fax-on-Demand SupportFax-on-Demand is a 24-hour information retrieval system containing a library of documents on awide range of technical information. You can access Fax-on-Demand from a touch-tone telephone at(512) 418-1111.

E-Mail Support (currently U.S. only)You can submit technical support questions to the applications engineering team through e-mail atthe Internet address listed below. Remember to include your name, address, and phone number sowe can contact you with solutions and suggestions.

[email protected]

Telephone and Fax SupportNational Instruments has branch offices all over the world. Use the following list to find thetechnical support number for your country. If there is no National Instruments office in yourcountry, contact the source from which you purchased your software to obtain support.

Telephone FaxAustralia 03 9879 5166 03 9879 6277Austria 0662 45 79 90 0 0662 45 79 90 19Belgium 02 757 00 20 02 757 03 11Canada (Ontario) 905 785 0085 905 785 0086Canada (Quebec) 514 694 8521 514 694 4399Denmark 45 76 26 00 45 76 26 02Finland 90 527 2321 90 502 2930France 01 48 14 24 24 01 48 14 24 14Germany 089 741 31 30 089 714 60 35Hong Kong 2645 3186 2686 8505Israel 03 5734815 03 5734816Italy 02 413091 02 41309215Japan 03 5472 2970 03 5472 2977Korea 02 596 7456 02 596 7455Mexico 95 800 010 0793 5 520 3282Netherlands 0348 433466 0348 430673Norway 32 84 84 00 32 84 86 00Singapore 2265886 2265887Spain 91 640 0085 91 640 0533Sweden 08 730 49 70 08 730 43 70Switzerland 056 200 51 51 056 200 51 55Taiwan 02 377 1200 02 737 4644U.K. 01635 523545 01635 523154

Technical Support FormPhotocopy this form and update it each time you make changes to your software or hardware, anduse the completed copy of this form as a reference for your current configuration. Completing thisform accurately before contacting National Instruments for technical support helps our applicationsengineers answer your questions more efficiently.

If you are using any National Instruments hardware or software products related to this problem,include the configuration forms from their user manuals. Include additional pages if necessary.

Name __________________________________________________________________________

Title ___________________________________________________________________________

Company _______________________________________________________________________

Address ________________________________________________________________________

_______________________________________________________________________________

Fax ( ____ ) _________________________ Phone ( ___ ) ___________________________

Computer brand ___________________ Model _____________ Processor ________________

Operating system (include version number) ____________________________________________

Clock Speed _________ MHz RAM __________ MB Display adapter________________

Mouse _____yes ____ no Other adapters installed _____________________________

Hard disk capacity ________ MB Brand ___________________________________________

Instruments used _________________________________________________________________

National Instruments hardware product model _____________________ Revision ___________

Configuration ___________________________________________________________________

National Instruments software product ____________________________ Version ___________

Configuration ___________________________________________________________________

The problem is __________________________________________________________________

_______________________________________________________________________________

_______________________________________________________________________________

_______________________________________________________________________________

List any error messages ___________________________________________________________

_______________________________________________________________________________

_______________________________________________________________________________

The following steps will reproduce the problem _________________________________________

_______________________________________________________________________________

_______________________________________________________________________________

Hardware and Software Configuration FormRecord the settings and revisions of your hardware and software on the line to the right of each item.Complete a new copy of this form each time you revise your software or hardware configuration,and use this form as a reference for your current configuration. Completing this form accuratelybefore contacting National Instruments for technical support helps our applications engineers answeryour questions more efficiently.

National Instruments ProductsHardware Revision _______________________________________________________________

Interrupt Level of Hardware ________________________________________________________

DMA Channels of Hardware ________________________________________________________

Base I/O Address of Hardware ______________________________________________________

NI-DAQ, LabVIEW, orLabWindows Version _____________________________________________________________

Other ProductsComputer Make and Model _________________________________________________________

Microprocessor __________________________________________________________________

Clock Frequency _________________________________________________________________

Type of Video Board Installed ______________________________________________________

Operating System ________________________________________________________________

Operating System Version __________________________________________________________

Operating System Mode ___________________________________________________________

Programming Language ___________________________________________________________

Programming Language Version _____________________________________________________

Other Boards in System ____________________________________________________________

Base I/O Address of Other Boards ___________________________________________________

DMA Channels of Other Boards _____________________________________________________

Interrupt Level of Other Boards _____________________________________________________

Documentation Comment FormNational Instruments encourages you to comment on the documentation supplied with our products.This information helps us provide quality products to meet your needs.

Title: NI-FBUSTM Function Reference Manual for Windows NT

Edition Date: December 1996

Part Number: 321288A-01

Please comment on the completeness, clarity, and organization of the manual.

_______________________________________________________________________________

_______________________________________________________________________________

_______________________________________________________________________________

_______________________________________________________________________________

_______________________________________________________________________________

_______________________________________________________________________________

_______________________________________________________________________________

If you find errors in the manual, please record the page numbers and describe the errors.

_______________________________________________________________________________

_______________________________________________________________________________

_______________________________________________________________________________

_______________________________________________________________________________

_______________________________________________________________________________

_______________________________________________________________________________

_______________________________________________________________________________

Thank you for your help.

Name __________________________________________________________________________

Title ___________________________________________________________________________

Company _______________________________________________________________________

Address ________________________________________________________________________

_______________________________________________________________________________

Phone ( _____ ) _________________________________________________________________

Mail to: Technical Publications Fax to: Technical PublicationsNational Instruments Corporation National Instruments Corporation6504 Bridge Point Parkway (512) 794-5678Austin, TX 78730-5039

© National Instruments Corporation G-1 NI-FBUS FRM for Windows NT

Glossary

Prefix Meaning Value

n- nano- 10-9

µ- micro- 10-6

m- milli- 10-3

A

AI Analog Input. A type of function block.

alarm A notification the NI-FBUS software sends when it detects that a blockleaves or returns to a particular state.

alert An alarm or an event.

argument A value you pass in a function call. Sometimes referred to as a parameter,but this documentation uses a different meaning for parameter, which isincluded in this glossary.

ASCII American Standard Code for Information Interchange.

Glossary

NI-FBUS FRM for Windows NT G-2 © National Instruments Corporation

B

block A logical software unit that makes up one named copy of a block and theassociated parameters its block type specifies. The values of theparameters persist from one invocation of the block to the next. It can bea resource block, transducer block, or function block residing within aVFD.

block context Describes a category of NI-FBUS functions that accept block descriptors.

block view objects Variable list objects used to read multiple block parameters at once.

D

DDOD Device Description Object Dictionary. The Device Description binary file.

descriptor A number returned to the application by NI-FBUS, used to specify atarget for future NI-FBUS calls.

device ID An identifier for a device that the manufacturer assigns. Device IDs mustbe unique to the device; no two devices can have the same device ID.

device tag A name you assign to a fieldbus device.

E

entity A certain thing, such as a process, object, device, or event.

event An occurrence on a device that causes a fieldbus entity to send thefieldbus event message.

F

fieldbus An all-digital, two-way communication system that connects controlsystems to instrumentation.

Glossary


Fieldbus Messaging The layer of the communication stack that defines a model forSpecification (FMS) applications to interact over the fieldbus. The services FMS provides

allow you to read and write information about the OD, read and write thedata variables described in the OD, and perform other activities such asuploading/downloading data, and invoking programs inside a device.

function block A named block consisting of one or more input, output, and containedparameters. The block performs some control function as its algorithm.function blocks are the core components you control a system with. TheFieldbus Foundation defines standard sets of function blocks. There areten function blocks for the most basic control and I/O functions.Manufacturers can define their own function blocks.

function block A list of times in the macrocycle when the function block willexecution schedule begin to execute its algorithm.

I

index An integer that the fieldbus specification assigns to a fieldbus object or adevice that you can use to refer to the object.

L

link A group of fieldbus devices connected across a single wire pair with nointervening bridges.

Link Active Schedule A schedule of times in the macrocycle when devices must publish theiroutput values on the fieldbus.

Link Active A device that is responsible for keeping a link operational. The LASScheduler (LAS) executes the link schedule, circulates tokens, distributes time and probes

for new devices.

link context Describes a category of NI-FBUS calls that accept link descriptors.

link ID See link identifier.

link identifier A number that specifies a link.

Link Master device A device that is capable of becoming the LAS.

Glossary


M

macrocycle One iteration of a the process control loop.

O

object attribute A part of the machine-readable description of a fieldbus object.

Object Dictionary (OD) A structure in a device that describes data that can be communicated onthe fieldbus. The OD is a lookup table that gives information such asdata type and units about a value that can be read from or written to adevice.

Object Dictionary A value in the object dictionary used to refer to a single object.index

object value The actual data value associated with a fieldbus object.

P

parameter One of a set of network-visible values that makes up a function block.

physical device A single device residing at a unique address on the fieldbus.

physical device Describes a category of NI-FBUS functions that accept physical devicecontext descriptors.

process variable A common fieldbus function block parameter representing some value inthe process being controlled.

publisher A device that has at least one function block with its output valueconnected to the input of another device.

R

resource block A special block which contains parameters that describe the operation ofthe device.

Glossary


S

sample type Specifies how trends are sampled on a device, whether by averaging dataor by instantaneous sampling.

session A connection between your application and an NI-FBUS entity.

session context Describes a category of NI-FBUS functions that accept sessiondescriptors.

stale Data that has not been updated for stale_limit number ofmacrocycles, where the stale limit is a parameter of the connection.

subscriber A device that has at least one function block with its input valueconnected to the output of another device.

symbol file A Fieldbus Foundation or device manufacturer-supplied file that containsthe ASCII names for all the objects in a device.

T

tag A name you can define for a block, VFD, or device.

thread An operating system object that consists of a flow of control within aprocess. In some operating systems, a single process can have multiplethreads, each of which can access the same data space within the process.However, each thread has its own stack and all threads can executeconcurrently with one another (either on multiple processors, or bytime-sharing a single processor).

timeout A period of time after which an error condition is raised if some eventhas not occurred.

transducer block A block that is an interface to the physical, sensing hardware in thedevice. It also performs the digitizing, filtering, and scalingconversions needed to present input data to function blocks, andconverts output data from function blocks. transducer blocks decouplethe function blocks from the hardware details of a given device,allowing generic indication of function block input and output.Manufacturers can define their own transducer blocks.

Glossary


trend A fieldbus object that allows a device to sample a process variableperiodically, then transmit a history of the values on the network.

V

variable list A list of variables you can access with a single fieldbus transaction.

VFD context Describes a category of NI-FBUS functions that accept VFD descriptors.

Virtual Field A model for remotely viewing data described in the object dictionary.Device (VFD)

© National Instruments Corporation I -1 NI-FBUS FRM for Windows NT

Index

Aadministrative functions

format of function information, 1-1to 1-2

list of functions (table), 1-2nifClose, 1-3 to 1-4nifGetBlockList, 1-5 to 1-7nifGetDeviceList, 1-9 to 1-10nifGetInterfaceList, 1-11 to 1-12nifGetVFDList, 1-13 to 1-14nifOpenBlock, 1-15 to 1-16nifOpenLink, 1-17 to 1-18nifOpenPhysicalDevice, 1-19 to 1-20nifOpenSession, 1-21 to 1-22nifOpenVfd, 1-23 to 1-24

alert and trend functionslist of functions (table), 3-1nifAcknowledgeAlarm, 3-2 to 3-3nifWaitAlert, 3-4 to 3-6nifWaitTrend, 3-7 to 3-8

Bbulletin board support, A-1

Ccore functions

list of functions (table), 2-1nifFreeObjectAttributes, 2-2nifGetObjectAttributes, 2-3 to 2-6nifGetObjectSize, 2-7 to 2-9nifGetObjectType, 2-10 to 2-16nifReadObject, 2-17 to 2-20nifWriteObject, 2-21 to 2-24using NI-FBUS interface macros, 2-25

to 2-26customer communication, xi, A-1 to A-2

Ddocumentation

conventions used in manual, x-xihow to use manual set, ix-xorganization of manual, xrelated documentation, xi

Eelectronic support services, A-1 to A-2e-mail support, A-2

Index

NI-FBUS FRM for Windows NT I -2 © National Instruments Corporation

FFax-on-Demand support, A-2FTP support, A-1

Iinterface macros, NI-FBUS, 2-25 to 2-26

Mmanual. See documentation.

NnifAcknowledgeAlarm, 3-2 to 3-3NI-FBUS interface macros, 2-25 to 2-26

core function macros (table), 2-25location in nifbus.h header file, 2-26specifying, 2-25 to 2-26

nifClose function, 1-3 to 1-4nifFreeObjectAttributes function, 2-2nifGetBlockList function, 1-5 to 1-7nifGetDeviceList function, 1-9 to 1-10nifGetInterfaceList function, 1-11 to 1-12nifGetObjectAttributes function, 2-3 to 2-6

context, 2-4description, 2-5format, 2-3 to 2-4input, 2-4output, 2-4purpose, 2-3return values, 2-5 to 2-6

nifGetObjectSize function, 2-7 to 2-9nifGetObjectType function, 2-10 to 2-16

context, 2-11data structure, 2-12data type, 2-12description, 2-12 to 2-15format, 2-10 to 2-11input, 2-11

object code elements, 2-13 to 2-14object codes for nifObjTypeList_t data

structure (table), 2-13output, 2-11pseudocode for getting type

information, 2-14purpose, 2-10return values, 2-15 to 2-16standard data types for

ODT_SIMPLETYPE object code(table), 2-15

typeIndex of elements, 2-14nifGetVFDList function, 1-13 to 1-14nifOpenBlock function, 1-15 to 1-16nifOpenLink function, 1-17 to 1-18nifOpenPhysicalDevice function, 1-19

to 1-20nifOpenSession function, 1-21 to 1-22nifOpenVfd function, 1-23 to 1-24nifReadObject function

context, 2-18description, 2-18 to 2-19format, 2-17 to 2-18input, 2-18output, 2-18purpose, 2-17return values, 2-19 to 2-20

nifWaitAlert function, 3-4 to 3-6nifWaitTrend function, 3-7 to 3-8nifWriteObject function, 2-21 to 2-24

context, 2-22description, 2-22 to 2-23format, 2-21 to 2-22input, 2-22output, 2-22purpose, 2-21return values, 2-23 to 2-24

Index

© National Instruments Corporation I-3 NI-FBUS FRM for Windows NT

Ssessions (note), 1-3

Ttechnical support, A-1 to A-2telephone and fax support, A-2trend functions. See alert and trend functions.

Documents

NI-FBUSTM Function Reference Manual for Windows NT