GE Fanuc Automation

VersaPro! 2.00

Variable Data Server

Public Interface Specification

Version	Date	Page-paragraph	Remarks
0	7-1-99		Original Issue

1 Introduction

• Introduction

The Variable Data Server is an in-process COM server which allows applications outside of VersaPro to read and write variable information from/to a variable data file in a VersaPro folder. Variable information is transferred to and from the Variable Data Server using the Shared Name File (SNF) format.

Please note that only variables in the VersaPro Variable Declaration Table with the Show External attribute set to True are visible to a client of the variable data server.

1. Definitions

COM Component Object Model

SNF Shared Name File

VDT Variable Declaration Table.

• Interface

The only interface available for the Variable Data Server is the COM interface. Variable information will be transferred from the client application to/from the server via the SNF format.

1. COM Interface

1. Standard Microsoft Interfaces

1. IPersistFile

The IPersistFile interface provides methods that permit the VDT file to be loaded from or saved to a disk file. The IPersistFile interface inherits its definition from the IPersist interface and so includes the GetClassID method of IPersist.

When to Implement

The client is required to implement this interface prior to setting or getting the variable information.

When to Use

This interface is to be used when the client wants to read/write the variable information from/to a VDT file.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.

IPersist Method	Description
GetClassID	Returns the class identifier (CLSID) for the component object.

IPersistFile Methods	Description
IsDirty	Checks an object for changes since it was last saved to its current file.
Load	Opens the specified file and initializes an object from the file contents.
Save	Saves the object into the specified file.
SaveCompleted	Notifies the object that it can revert from NoScribble mode (in which it must not write to its file), to Normal mode.
GetCurFile	Gets the current name of the file associated with the object.

2. ISupportErrorInfo

The ISupportErrorInfo interface ensures that error information can be propagated up the call chain correctly for Automation objects.

When to Implement

This interface is required for Automation servers by Microsoft.

When to Use

This interface is required for Automation servers by Microsoft.

Methods in Vtable Order

ISupportErrorInfo Methods	Description
InterfaceSupportsErrorInfo	Indicates whether the interface identified by riid supports the IErrorInfo interface.

3. IDispatchImpl

IDispatchImpl provides a default implementation for the IDispatch portion of any dual interface on your object. A dual interface derives from IDispatch and uses only Automation-compatible types.

When to Implement

An Automation type client (ex. Visual Basic) will implement this interface or a client that wishes to use the Automation interface.

When to Use

This interface should only be used by Automation type clients.

Available Methods

IDispatchImpl Methods	Description
IsDirty	Checks an object for changes since it was last saved to its current file.
Load	Opens the specified file and initializes an object from the file contents.
Save	Saves the object into the specified file.
SaveCompleted	Notifies the object that it can revert from NoScribble mode (in which it must not write to its file), to Normal mode.
GetCurFile	Gets the current name of the file associated with the object.
SetSNFData	Provides the mechanism to transfer information from the client to the server.
GetSNFData	Provides the mechanism to transfer information from the server to the client.

1. HRESULT IsDirty(BOOL * pbDirtyFlag)

Checks an object for changes since it was last saved to its current file. This method supports the IPersistFile interface.

1. Parameters

pbDirtyFlag - A pointer to a BOOL which indicates whether the file is modified (dirty).

2. Return Value

An HRESULT containing S_OK if successful otherwise E_FAIL.

2. HRESULT Load(BSTR bstrFileName, DWORD dwMode)

Opens the specified file and initializes an object from the file contents. This method supports the IPersistFile interface.

1. Parameters

bstrFileName - A BSTR containing the absolute path of the file to open.

dwMode - A DWORD containing the access mode from the STGM enumeration values.

2. Return Value

An HRESULT containing S_OK if successful otherwise E_FAIL.

3. HRESULT Save(BSTR bstrFileName, BOOL fRemember)

Saves the object into the specified file. This method supports the IPersistFile interface.

1. Parameters

bstrFileName - A BSTR containing the absolute path of where the file is to be saved.

dwMode - A BOOL specifying whether the file is to be the current working file or not.

2. Return Value

An HRESULT containing S_OK if successful otherwise E_FAIL.

4. HRESULT SaveCompleted(BSTR bstrFileName)

Notifies the object that it can revert from NoScribble mode (in which it must not write to its file), to Normal mode. This method supports the IPersistFile interface.

1. Parameters

bstrFileName - A BSTR containing the absolute path of where the file was saved.

2. Return Value

An HRESULT containing S_OK if successful otherwise E_FAIL.

5. HRESULT GetCurFile(BSTR * pbstrFileName)

Gets the current name of the file associated with the object. This method supports the IPersistFile interface.

1. Parameters

pbstrFileName - A pointer to a BSTR where the absolute path of where the file was saved should be placed.

2. Return Value

An HRESULT containing S_OK if successful otherwise E_FAIL.

6. HRESULT SetSnfData(BSTR bstrSnfData)

This method provides the mechanism to transfer information from the client to the server. This method supports the IHSnfXfer interface.

1. Parameters

bstrSnfData - A BSTR containing the variable information in the SNF format.

2. Return Value

An HRESULT containing S_OK if successful otherwise E_FAIL.

7. HRESULT GetSnfData(BSTR * bstrSnfData)

This method provides the mechanism to transfer information from the client to the server. This method supports the IHSnfXfer interface.

1. Parameters

bstrSnfData - A pointer to a BSTR where the variable information in the SNF format should be placed.

2. Return Value

An HRESULT containing S_OK if successful otherwise E_FAIL.

2. Custom Interfaces

1. IHSnfXfer

The IHSnfXfer interface provides methods that permits the variable information to be transferred to/from a client using the SNF format.

When to Implement

The client is required to implement this interface prior to setting or getting the variable information.

When to Use

This interface is to be used when the client wants to transfer the variable information from/to a VDT file.

Available Methods

IHSnfXfer Methods	Description
SetSNFData	Provides the mechanism to transfer information from the client to the server.
GetSNFData	Provides the mechanism to transfer information from the server to the client.

1. HRESULT SetSnfData(BSTR bstrSnfData)

This method provides the mechanism to transfer information from the client to the server.

1. Parameters

bstrSnfData - A BSTR containing the variable information in the SNF format.

2. Return Value

An HRESULT containing S_OK if successful otherwise E_FAIL.

3. Sequence Diagram

2. HRESULT GetSnfData(BSTR * bstrSnfData)

This method provides the mechanism to transfer information from the server to the client.

1. Parameters

bstrSnfData - A pointer to a BSTR where the variable information in the SNF format should be placed.

2. Return Value

An HRESULT containing S_OK if successful otherwise E_FAIL.

3. 
   Sequence Diagram

• VersaPro Format of the Shared Name File

The Shared Name File (or SNF) format is an extension of the industry-standard Comma Separated Variable (CSV) format. SNF files contain two types of information, Comments and Records. Comment lines begin with the Comment Line Sequence ## (i.e., two consecutive pound characters as the first non-blank characters in the line). Records (except for Header Section records (see below)) do not begin with the Comment Line sequence.

1. General SNF Format Rules

• Shared Name Files shall have a default extension of “.SNF”. it is recommended that the filename be the same as the source file (folder) from which the SNF is generated.

• Comment lines begin with the double pound sign (“##”) character sequence as the first non-blank character.

• Comment lines may appear anywhere within the SNF, but may not occur inside a record.

• Records continued over several lines may not have intervening comment lines.

• The SNF will consist of three sections which must occur in order:

• (1) optional Header section

• (2) required Field Names section

• (3) required Data section.

• All sections are made up of comma separated variable (CSV) records. Each CSV record is composed of a list of fields separated by commas. Individual fields may be enclosed within double quotation marks, and fields that contain commas must be enclosed within quotes.

• All records in a section must include the same fields, and the fields must be in the same order in each record. Fields in records may be left empty, but empty fields must be delimited with commas like all other fields.

• Spaces surrounding the comma delimiters in a record are ignored. To include leading or trailing spaces in a field, surround the field with quotation marks.

• Records may span one or more lines of text in an SNF file. A line of text in an SNF file ends with the new line character ( or character sequence) appropriate for the operating system. The last line of text in the file must include a new line character.

• Any line beginning with a double colon sequence (::) is considered a continuation of the record started on the previous line. Fields must be contained within a single line, and their trailing comma delimiter must follow the field on the same line as the field. i.e. ( lines of text followed by continuation lines must end in a non-quoted comma.)

• Blank lines are not allowed.

• The maximum line size is 2000 characters.

• The maximum record size is 2000 characters not counting continuation characters and new line characters.

• The maximum number of fields in a record is 100.

1. Header Section Rules

• Header section records may not span multiple lines

• The Header section contains structured comments which provide some context for the file

• All header section entries must be accepted by any package using the SNF format, but they need only interpret and use the ones they recognize.

1. Field Names Section Rules

• The Field Names Section contains one and only one record.

• The Field Names Section begins with the first non-comment line in the file.

• Field Names are case insensitive

• PT_ID must be the first field in the Field Names section.

• No empty fields are permitted in the Field Name section

1. Data Section Rules

• The Data Section follows the Field Names Section

• The Data Section begins on the first non-comment line after the Field Name section and continues to the end of the file.

• Predefined Keywords in the Data section are case insensitive

• PT_IDs in the Data Section are case insensitive

• Empty fields are permitted in the Data section, but commas must delimit them.

• If the PT_ID field is empty, the ADDR field must be present and not empty.

• The format of numbers shall be whatever Excel 5.0 uses as default when creating a CSV files.

1. Header Section

This section of the SNF contains fields that define the context of the SNF. The Header section has five keywords currently defined. It is expected that GE Fanuc will define additional keywords and that customers will wish to add their own keywords.

##&&Creator	This identifies the application that specified the content of this SNF file. Five possible values generated by GE Fanuc programs are: “VersaPro”, “CIMPLICITY Control”, “CIMPLICITY”, “LOGICMASTER”, or “PROCESS_90”. Other values for this field will not cause an error.
##&&CreateDate	This specifies the date when this SNF file was created. The date format shall be in the format “(d)d-mmm-yyyy”. For example, 31-MAY-1994, 4-NOV-1986, or 11-Sep-1994
##&&ProgDate	The date of the creation of the program with which this SNF file is associated
##&&FileType	This identifies what type of data is contained within this SNF. VersaPro specifies a value of : “I/O”.

If the ##&&Creator field is omitted, it is assumed that a non-GE Fanuc application created the SNF file. If the ##&&FileType field is omitted, it is assumed that the SNF file contains only I/O point data (i.e. - a file type of “I/O” is the default).

The following is an example Header section of a SNF.

##

## This is a Shared Name File (SNF) used to pass

## Tag Names (mnemonic references) among industrial

## applications.

##

##&&Creator,VersaPro®

##&&CreateDate, 09-Dec-1999

##&&ProgDate, 04-Dec-1999

##&&FileType,I/O

##

2. Field Names

This section of the SNF is used to specify the names of the fields in the Data section, and the order of these named fields. The order of the fields in the Field Names section is the order to be used in all records of the Data section. The following is an example Field Names section of a SNF.

##

PT_ID,ADDR,DESC,PT_TYPE,LENGTH,RETENTIVE,OVERRIDE,STORED_VAL,SHOW_EXT

##

The possible field names recognized by VersaPro are:

Field Name	Meaning of This Field
PT_ID	Tag Name (or Variable Name) of this point *
ADDR	A mnemonic reference to a PLC memory location.
DESC	An ASCII string describing what data this point represents.
PT_TYPE	What type of data is being described by this point.
LENGTH	The array length for this point.
RETENTIVE	Indicates whether or not the point should retain its value when a power cycle occurs.
OVERRIDE	Indicates whether or not the point is overridden by default when logic is stored to the PLC.
SHOW_EXT	Indicates whether or not the point is visible to other packages.
STORED_VAL	Indicates the value(s) stored to the location of the point when logic is stored to the PLC.

* - This is a required field for the FIELD NAME section and must be the first Field Name.

See sections on required support by other GE Fanuc products to determine which fields they support.

Additional fields that are not supported by the importing program will be ignored without error. Warnings that addition fields are being ignored are recommended.

The following is an in-depth description of each field mentioned above.

1. PT_ID Field

PT_ID - The tag name (variable name) may be up to thirty-two (32) characters in length. A variable name can be no longer than 31 characters, and may only consist of the characters A - Z, a - z, 0 - 9, _, +, -, #, @, <, >, =. Variable names must start with a letter or underscore ("_").

2. ADDR Field

ADDR - The GE Fanuc PLC reference table location. This address may appear in two possible formats: “%<memory type><memory offset>“ (such as %R0256) or “%<memory type><memory offset>,<block name>“ (such as “%R0734,BATCH6”). The memory offset portion of the address field may or may not have leading zeroes. Thus, %R25, %R025, %R0025, etc. are all equivalent. The second form of the address must always be enclosed in double quotes. The “block name” portion of the second form of the address refers to a PLC subprogram block name for Local scope variables.

3. DESC Field

DESC - This is an ASCII string of printable characters designed to be a human-readable description of what this point is used for in this application. If this field contains a comma, it must be enclosed in double quotes. The DESC may be up to 64 characters in length. This field is case sensitive.

4. PT_TYPE Field

PT_TYPE - The data type of this point. The possible valid values of this field for VersaPro are as follows. When VersaPro creates an SNF file it will only create PT_TYPEs of BOOL, BYTE, and WORD since these are the only data types supported by VersaPro. When VersaPro imports types that are not supported, the types are converted to supported VersaPro types and an appropriate length.

PT_TYPE	Correspondig VersaPro Data Type and Length
WORD	WORD, LENGTH = 1
BYTE	BYTE, LENGTH 1
BOOL	BIT, LENGTH 1
UINT	WORD, LENGTH = 3
REAL	WORD, LENGTH = 2
DINT	WORD, LENGTH = 2
DWORD	WORD, LENGTH = 2
CTU	WORD, LENGTH = 3
CTD	WORD, LENGTH = 3
TMR_TENTHS	WORD, LENGTH = 3
TMR_HUNDS	WORD, LENGTH = 3
TMR_THOUS	WORD, LENGTH = 3
OFDT_TENTHS	WORD, LENGTH = 3
OFDT_HUNDS	WORD, LENGTH = 3
OFDT_THOUS	WORD, LENGTH = 3
BIT_SEQ	WORD, LENGTH = 3
SER	WORD, LENGTH = 78
PID_ISA	WORD, LENGTH = 40
PID_IND	WORD, LENGTH = 40

5. LENGTH Field

LENGTH - The array length for this point. Thus, if the PT_TYPE of the point is WORD and the LENGTH is 2, then this point represents an array of two words. If the field is left empty, the default length for the point is one (1). For VersaPro, if the PT_TYPE is BOOL, this field must have the value 1.

6. RETENTIVE Field

RETENTIVE - Indicates whether or not the point should retain its value when a power cycle occurs. The string “YES” indicates that the point is retentive and the string “NO” indicates that the point is not retentive. Any other non-empty string will cause an error to be generated when the SNF file is imported. If an empty string is specified, then the retentive setting default to the appropriate value for the specified address.

7. OVERRIDE Field

OVERRIDE - Indicates whether or not the point is overridden by default when logic is stored to the PLC. The string “YES” indicates that the point is overridden by default on store and the string “NO” indicates that the point is not overridden by default on store. Any other non-empty string will cause an error to be generated when the SNF file is imported. If an empty string is specified, then the override setting defaults to “NO.”

8. SHOW_EXT Field

SHOW_EXT - Indicates whether or not the point is visible to other packages. The string “YES” indicates that the point can be made visible to other packages while the string “NO” indicates that it cannot. Any other non-empty string will cause an error to be generated when the SNF file is imported. If an empty string is specified, then the Show Externally defaults to “NO.”

9. STORED_VAL Field

STORED_VAL - Indicates the value(s) stored to the location of the point when logic is stored to the PLC. The values in this field must be appropriate for the PT_TYPE specified for the point. Thus, if the PT_TYPE is BOOL, only the values 0 or 1 are valid for this field. Any other value will cause an error when the file is imported. Likewise if the PT_TYPE is INT, a value of 40000 will cause an error when the file is imported. If the LENGTH of the point is greater than 1, more than one value may be specified in this field. A comma separates each consecutive value and the entire field must be enclosed in quotes. Thus, if the PT_TYPE for the point is BYTE and the LENGTH is 5, an acceptable STORED_VAL field would be “1,0,1,0,1”. Note that all five values do not have to be specified, but the first value specified is always associated with the first element of the array. An error will also be reported during the imported if too many Stored Values are specified for the point. Thus, if the PT_TYPE is BYTE and the LENGTH is 2, a Stored Value such as “1,0,1” will cause an error on import. Similar values are possible for points with structured types, e.g. TMR_HUNDS.

10. Field Name Summary

The following table summarizes the Field Names.

			Field	Entry
Field Name	Data Type	Size	Required	Required	Defaults
PT_ID	String	up to 31 characters	Yes	no	None
ADDR	Address String	two formats - up to 8 or 18 characters	No	no	None
DESC	String	up to 64 characters	No		None
PT_TYPE	Keyword Flag	19 values	No	yes Use Defaults	WORD, BOOL
LENGTH	UINT	16 bits	No	no	Default is 1
RETENTIVE	String	3 characters	No	no	Default is “NO”
OVERRIDE	String	3 characters	No	no	Default is “NO”
SHOW_EXT	String	3 characters	No	no	Default is “NO”
STORED_VAL	String	N/A	No	no	None

3. Data Section

This section contains records that describe the actual point data that is being conveyed by the SNF. This section is a mandatory section of the SNF. There is exactly one point per record. A comma separates the fields of each record. If the contents of a field is not to be specified (for example, omit the DESCRIPTION field), then the field is empty but a comma is still required. It will not be considered an error if additional commas appear at the end of a record line.

4. SNF Example

The following is an example SNF file with all three sections present.

##

##&&Creator,VersaPro®

##&&CreateDate, 16-Dec-1999

##&&ProgDate, 10-Dec-1999

##&&FileType,I/O

##

PT_ID,ADDR,DESC,PT_TYPE,LENGTH,RETENTIVE,OVERRIDE,STORED_VAL,SHOW_EXT

##

SNSFAIL,%I00001,Temperature Sensor Failure,BOOL,1,YES,NO,,NO

LOTEMP,%I00002,Low Temperature Alarm,BOOL,1,YES,NO,,NO

TEMPOK,%I00003,Temperature OK,BOOL,1,YES,NO,,NO

VersaPro! 1.1
Variable Data Server

Confidential		Public Interface Specification
		Revision History

ii

iii

© Copyright 1999 GE Fanuc Automation North America, Inc. All Rights Reserved

VersaPro 1.1
Variable Data Server

		Public Interface Specification
		Table of Contents

iii

VersaPro 1.1
Variable Data Server

VersaPro! 1.1
Variable Data Server

		Public Interface Specification
		VersaPro Format of the Shared Name File

Variable Data Server
Page 12 of 13 (1)		2000-06-15 14:37

		Variable Data Server
2000-06-15 14:37		Page 11 of 13 (1)

---