This function returns the list of communication parameters for the specified device type, host, and device.

Syntax:

CS_RETCODE ASC_loadCommParams(CS_CHAR devType, const CS_CHAR *clli, const CS_CHAR *device, COMM_PARAM_ST **commParams))

Arguments:

• devType: The type of device to load the parameters.

• clli: The host clli to load the parameters.

• device: The device ID to load the parameters.

• commParams: This is a pointer to the created list of communications parameters. Upon failure, or if there are no communications parameters, commParams is set to 0.

Return Values:

• CS_SUCCEED: Operation was successful.

• CS_FAIL: Operation failed.

This function initializes the communications interface library. When interface-specific State Table actions are required by the NEP, you use this function to register the actions with CMD_user_actions.

This function is only required if you are using the ASC communication interface. In other words, if you are building your own communication interface, this function is not required.

For more information on CMD_user_actions, refer to "CMD_user_actions."

Syntax:

CS_RETCODE CMD_comm_init(void)

Return Values:

• CS_SUCCEED: Initialization of the NEP was successful.

• CS_FAIL: Initialization failed.

This function opens the connection to the device specified by the port information structure. It registers an association between the command processor initiating the connect and the device. This function is supplied by the NEP application. However, if the NEP application links to libasccomm, the custom NEP does not need to define this function.

Syntax:

CS_RETCODE CMD_connect_port(CMD_PORT_INFO *port)

Arguments:

• port: Pointer to the port information data structure.

Return Values:

• CS_SUCCEED: Connection was successful.

• CS_FAIL: Connection attempt failed.

This function closes the connection to the device specified by the port information structure. This function is supplied by the NEP application. However, if the NEP application links to libasccomm, the custom NEP does not need to define this function.

Syntax:

CS_RETCODE CMD_disconnect_port(CMD_PORT_INFO *port, SRV_OBJID cmd_qid)

Arguments:

• port: Pointer to the port information data structure.

• qid: Auxiliary command processor message queue ID.

This function maps generic feature names to the feature name for the switch in tbl_march_feat.

This function adds a provisioning parameter to the NEP database (tbl_march_rpm).

This function deletes a mapping from a generic feature name to the feature name for a switch type from tbl_march_feat.

If you invoke the procedure without any parameters, all rows in the database table are deleted.

This function deletes provisioning parameter(s) from tbl_march_rpm.

If you invoke the function without any parameters, all the rows in the database table are deleted.

To delete all USOC parameters for all hosts, the following command can be used:

NEP_del_parm type = HU.

This function displays the mapping of generic feature names to switch feature names based upon switch type. This information is contained in tbl_march_feat.

If you invoke the procedure without any arguments, all mapping records are displayed.

This function is used to show provisioning parameter(s) contained in tbl_march_rpm.

If you invoke the function without any arguments, all the provisioning parameters are displayed. To show all USOC parameters for all hosts, use the following command:

NEP_show_parm type = "HU" 

This function dumps the virtual screen for the specified port to a file.

Syntax:

screen_dump  @device, @filename

This function enables the tbl_resource_pool to dump data from the virtual screen, assigned to each device (port), into the specified file. If the file already exists, the data shall be appended to the file.

This RPC shall be useful during testing and debugging of devices.

Syntax:

screen_enable  @device, @filename

This function disables continuous dumping of the virtual screen diagnostics, enabled by RPC screen_enable, into the file.

Syntax:

screen_disable @device

This function enables a continuous line diagnostics dump of the specified device (port), from the tbl_resource_pool of $SARM_DB.

Syntax:

line_enable  @device, @filename

This function disables the line diagnostics dump of the specified device (port), from the tbl_resource_pool of $SARM_DB.

Syntax:

line_disable @device

This function allows the External Device Driver (EDD) to dump data of the specified debugging type into the file. Depending on EDD implementation, the requested output can overwrite the file or append to the file.

Syntax:

edd_diag @device, @filename, @type

This function allows an administrative enabling (setting) of the device (port), from tbl_resource_pool of $SARM_DB.

Syntax:

enable @device

This function allows an administrative disabling of the device (port), from tbl_resource_pool of $SARM_DB. For the device (port) in the connected state, the disconnection is issued.

Syntax:

disable @device

This function initializes the Switch Configuration library. Currently, this function adds support for March, DMS, and blackout-related functions. This routine must be called from the CMD_comm_init() function in the custom NEP application. For more information on CMD_comm_init, see "CMD_comm_init."

Syntax:

CS_RETCODE ASC_libnecfg_init(void)

Return Values:

• CS_SUCCEED: Switch configuration library was successfully initialized.

• CS_FAIL: Initialization has failed. The NEP server diagnostics recognize the problem.

A TL1 action automatically inserts ASDL parameters (more precisely State Table variables) into the corresponding blocks of a TL1 input message, according to the prefix of the parameters. The dot notion is used to specify the prefix. For example, BLK_A.OE denotes that the parameter OE is in the block BLK_A. While ASAP provides default names for a block, these default names can be overridden in the State Table programs.

If there is no parameter for an optional block, an empty block is formed by the action function.

The TL1 action constructs a parameter block with name-defined parameters. The exception is in the case of a block that allows only position-defined parameters, for instance, Target Identifier Block.

Once a TL1 input message is constructed, you invoke a TL1 process action to trigger the NE to process the message. The process action blocks the State Table until all output messages are received or a time-out occurs. When the action times out, it aborts the process.

Some TL1 output messages are machine-parsable. TL1 actions can access TL1 output message blocks.

A parser parses both name-defined parameters and position-defined parameters of output messages. Parsed parameters are saved as State Table variables with either parameter names or position identifiers. You can then access output data items directly through State Table variables.

TL1 support in ASAP is provided in the NEP through a State Table program executed in a thread. The technical implementation of TL1 support consists of a set of action functions and a parser.

Action functions are implemented using current ASAP libraries that provide the basic building blocks for action functions.

TL1 support constructs TL1 input messages using name-defined parameters wherever valid (based on the Bellcore definition). This method is used because of its suitability for machine-to-machine interfaces.

The parser is a new layer built on the top of the ASAP communication unit: multiple protocol manager that is transparent to all communication protocols. This plug and play layer ensures that the NEP is fully backward-compatible.

TL1 actions interface with an NE in an interactive mode. Typically, it sends a command to a network element and waits for responses. In addition to this synchronous processing of each State Table program, ASAP processes more than one State Table program simultaneously through multiple connections to network elements.

To automatically insert parameters into the correct block when constructing a TL1 message, pre-agreed block names are used. ASAP internally keeps default block names, but you can choose block names by overriding the defaults in the State Table programs. To override default block names, pass new block names as arguments to the TL1 action. The following block names can be modified:

For all parameters in <general block> block, the parameters can have names such as TL1_GB. ON, TL1_GB.DATE, etc. To put the parameter LINE into the first <message payload block>, the parameter is TL1_MSG[1].LINE.

If there is no parameter found for a certain block, the action constructs an empty block or returns an error if it is a mandatory block.

The message payload block must be in sequence. The action function stops adding message blocks into a TL1 message whenever there are no remaining parameters for that block. If there are no parameters for <message payload block> two, TL1_MSG[2], the action function will not append TL1_MSG[3] even if there are parameters for it.

Some vendors add blocks (not in conformity with the recommendation), but do not use them, so that empty blocks are required. To do this, it is necessary to create dummy parameters to generate empty message payload blocks.

A variable name must have a block name and a TL1 parameter name. The TL1 action strips off the block name before it constructs a block. The TL1 parameter name is the name that is inserted into the corresponding block.

For example, in the block TL1_MSG[1] there are three parameters:

:OC=OC3, GOS=COT_GOS4, PST=OOS:

You must have the State Table variables TL1_MSG[1].OC=OC3, TL1_MSG[1].GOS=COT_GOS4, and TL1_MSG[1].PST=OOS.

TL1 acknowledgments consists of <acknowledgment code> and <ctag> and the TL1 response consists of a response header, an identification portion, and a text block.

<header> <response identification> [<text block>] <terminator>

where the following formats apply:

Header

<cr><lf><lf>^^^<sid>^<year>-<month>-
<day>^<hour>:<minute>:<second>

Response Identifier

<cr><lf>M^^<ctag>^<completion code>

Text Block

((<cr><lf>^^^<unquoted line>)|(<cr><lf>^^^<quoted line>)|(<cr><lf>^^^<comment>))*

TL1 actions provide the means to process TL1 output messages. The messages are automatically parsed and stored in State Table variables. ASAP provides default base names for the variables, but they can be overridden in State Table programs. An identifier is used as a sub-name to further identify data items in the block. The following table lists the base names and identifiers.

All variables that save parsed data items have the format base_name.identifier. The exception is TL1_COMMENT.

For example, TL1_ACK.CODE=IP. TL1_QUOTED, TL1_UNQUOTED, and TL1_COMMENT can appear zero or more times. Therefore an array identifier [n] is appended to base name forming a block name. For example, TL1_UNQUOTED[2].B[1].P[3]=5 means that 5 is the third parameter of the first block in the second <unquoted line> block.

An array index [i] is appended to the base name, block and position-defined parameter even if there is only one occurrence of the item. For example, if there is only one block in <unquoted line>, B[1] is used.

After a variable is assigned, you can access it in the same way as other State Table variables.

The TL1_BUILD_MSG action is used to construct a TL1 message from State Table variables.

See also TL1_PROCESS_MSG, BUILD_STRUCT.

This action constructs a TL1 message using state table variables.

• MSG_ID – Used to save the identifier of the input message

• %CMD – TL1 command code

• %TID – TL1 target identifier

• %AID – Access identifier

• %CTAG – TL1 correlation tag

• %TID – Optional argument

The following optional arguments are used to override default block base names. If changed, they both must be changed.

The default base names are:

• TL1_GB – General block

• TL1_MSG – Message payload block(s)

Upon invocation, the TL1_BUILD_MSG action function finds the variables matching the prefix block names among all state table variables. The matching parameters are then inserted into the corresponding blocks.

Since message payload block(s) can appear more than once, an array identifier is appended to the base. This identifier forms the block name. For example, TL1_MSG[1] identifies the first base name, TL1_MSG[2] identifies the second, and so on.

The action function searches for matching base name parameters until there is no match for that array number. For example, if there is a parameter TL1_MSG[1].name and TL1_MSG[3].value, only the name parameter is added.

Colons in the action syntax are action delimiters and do not pertain to TL1 block delimiters. The arguments in the last square bracket are the base names used to replace default base names; however, the arguments before it are the data which is inserted into the TL1 input message.

TL1_PROCESS_MSG is used to send this input message to the NE and then retrieve the resulting TL1 output message.

Errors:

State Table program execution ends in failure if you do not provide correct information. You must provide a command and a CTAG. Both the TID and AID are optional, however, the colons between them are not.

Syntax:

TL1_BUILD_MSG ‘MSG_ID=%CMD:[%TID]:[%AID]:%CTAG [: %GB_BASE:%MSG_BASE]'

Example:

The following example displays OC and PST going into the first message payload block. You must first construct parameters:

TL1_MSG[1].OC=OC3 and TL1_MSG[1].PST=OOS

The following example displays a portion of a State Table program using the action:

# Construct a message using saved values for AID, TID and inputted values for command and CTAG. Default base names for general block and message block will be used.
...
1000 TL1_BUILD_MSG ‘%MSG_1=UPDATE:%TID:%AID: C10-10'
# Trigger the NE to process message and wait 60 seconds for output message before it times out

1100 TL1_PROCESS_MSG ‘%MSG_1' 60
...

The TL1_PROCESS_MSG action sends the target NE a TL1 input message and then processes the output message.

This action must be used only after a message is constructed with TL1_BUILD_MSG, otherwise it may cause a failure of the program.

Once the output message is received, the message is parsed and information is stored in state table variables. The variable names consist of two parts: base name and identifier. The action provides default base names for variables, but you can change base names through variable or constant arguments presented in square brackets. If you are changing base names, you must either change all of them or none of them.

Each type of argument exhibits different behavior. Variable arguments represent State Table parameters. Constant arguments are static parameters that have no external reference.

Variable Argument:

2030  CONCAT '%TEST1=LABEL1'
2050  CONCAT '%TEST2=LABEL2'
2080  CONCAT '%TEST3=LABEL3'
2100  CONCAT '%TEST4=LABEL4'
2130  CONCAT '%TEST5=LABEL5'
2140  CONCAT '%TEST6=LABEL6'
3000  TL1_PROCESS_MSG '%MSG1=%TEST1:%TEST2:%TEST3:%TEST4:%TEST5:%TEST6' 60

Constant Argument:

3000  TL1_PROCESS_MSG '%MSG1=LABEL1:LABEL2:LABEL3:LABEL4:LABEL5:LABEL6' 60

Although they demonstrate different approaches, both examples have the same end result: the change of a base name. The base names as shown in both examples change to LABEL1 through LABEL6.

For example, if you want to change the default base names when storing the TL1 output message values, you would set up the State Table as follows:

1000 CONCAT '%ACK=AAA'
1100 CONCAT '%HDR=HHH'
1200 CONCAT '%RESP=RRR'
1500 TL1_PROCESS_MSG'%MSG1=%ACK:%HDR:%RESP:QUOTED:UNQUOTED:COMMENT'

When storing the output message values, the following values are valid:

• Ack message – AAA.CODE

• Header message – HHH.SID

• Response message – RRR.CODE

• Quoted message – QUOTED.B[1].P[1]

• Unquoted message – UNQUOTED.B[1].P[1]

• Comment message – COMMENT[1]

The timeout value specifies the maximum time of execution for this action function.

After the successful execution of this action, information can be accessed through these defined variables. The following table displays the relationship between an argument and output message.

Errors:

Communication problems and timeouts trigger ASAP to automatically reprocess the related ASDL later. If one base name is changed, all of the other base names must contain a value in the action string.

Failure to execute within the timeout value specified causes a communication failure.

Syntax:

TL1_PROCESS_MSG ‘%MSG_ID[=%ACK:%HEADER:%RESP_ID:%QUOTED:%UNQUOTED:%COMMENT]' timeout

Example:

# Construct a message
...
1000 TL1_BUILD_MSG ‘%MID=%UPDATE:::RDBKNJNVK01'
# Process the message and wait the output message for 120 sec. before time-out
1110 TL1_PROCESS_MSG ‘%MID' 120
# Check results
1200 IF_THEN ‘%TL1_RESP_ID.CODE==COMPLD'
1300 TL1_BUILD_MSG ‘%MSG2 = %RTRV: %TID: %AID: C11'
# this is an example where the default base names are changed. Note that both constants and State Table variables can be used.
1400 TL1_PROCESS_MSG ‘%MSG2 = %ACK:HHH:%RESP:‘%QUOTED:TL1_QUOTED2:%COMMENT:60
1500 ELSE
...
1600 END_IF
...

Constructs a TL1 test session between an OS and an NE using state table variables. in this way, an AID value is an alias which represents the tested objects. Bellcore TR-NWT-000831 provides some examples of how to use this feature.

• %MSG_ID – Used to save the identifier of the input message.

• CMD – TL1 command code.

• TID – TL1 target identifier.

• AID – TL1 access identifier.

• CTAG – TL1 correlation tag.

• TID – An optional argument.

The last optional parameter is a base name used to automatically construct parameter blocks. All State Table variables matching the block name (base name + [n]) is inserted into the block. The default base name is TL1_MSG and can be changed using the optional MSG_BASE argument.

TL1_PROCESS_MSG must be used to retrieve the TL1 output message after execution of this action.

Errors:

Program execution ends with failure if you do not provide correct information. If the communication channel is not available, the ASDL that triggers this action is retried.

Syntax:

TL1_BUILD_TSN                       ‘%MSG_ID=%CMD:[%TID]:%AID:%CTAG:%TSN
[:%MSG_BASE]'

Example:

# Construct a test session using command ‘CONN-TACC', no TID, AID ‘3-24' CTAG ‘1234', and test session ‘T1'
...
1100 TL1_BUILD_TSN ‘%MID=CONN-TACC::3-24:1234:T1'
...

With the signal approach, the EDD application has no control over the events that transmit data from the NEP, however, a UNIX signal interrupts the EDD when data arrives. The EDD application must be written to call a function in libgedd to retrieve the data whenever it detects an interruption by the SIGIO signal. Libgedd maintains an internal data structure to store the connection information. Each connection has its own node of the structure and is identified by an index. The EDD application must use the functions in libgedd to update and access this data structure if it is necessary.

There is a limitation for this approach. Most UNIX functions are written to return the control to the caller when a signal goes off. If the monitor of the communication API is written in this way, the signal approach is used. Some functions do not pass the control back to the caller even if there is a signal, but simply reprocess internally. If so, the only choice is to repeatedly poll on both connections. This creates a problem with performance.

The EDD application must pass the UNIX file descriptor associated with each connection (EDD to NEs) it maintains to the libgedd. The libgedd polls on all connections. The poll function returns an index to the application to identify the connection over which the data is received. The application uses routines provided by the libgedd to retrieve and send data from the NEP. The communication API provides routines to forward and receive data from the NEs.

In this approach, the application polls the connections (EDD to NEP) on behalf of the libgedd. Once it detects an event on a connection, it uses the routines provided to retrieve data.

This structure describes the data used by libgedd to track connections to its managers and the data used by an EDD application to track connections to its managers. The library libgedd owns this structure and provides a set of routines for the application to access it. No application should access this structure directly.

Syntax:

typedef struct edd_info_st {
int fd; 
int node_idx;  
int node_ind;
CS_BOOL in_use;
int debug;
FILE *debug_fptr;
char debug_fname[EDD_DEBUG_FNAME_L+1];
char device[CMD_PROC_DEV_L+1];
CS_BINARY *buf;
int len;
int comm_type;
EDD_COMM_PARAM_ST *comm_param;
int comm_param_len;
void *appl_data;
void (*appl_free)( void *appl_data );
}EDD_INFO_ST;

Public members:

• fd: File descriptor of the connection.

• node_idx: Index identifies the connection.

• node_ind: Identifies whether a connection is to the NEP or NE.

• in_use: Identifies whether this entry is used.

• debug: Identifies whether the debugger is turned on.

• debug_fptr: File pointer of the debug file that contains dumped information.

• debug_fname: Debug file name.

• device: Device name in NEP related to this connection.

• buf: Temporary place to save the data coming from NEP.

• len: Length of data saved in buf.

• comm_param: Communication parameters for this connection. These parameters are saved in the ASAP database and sent to the EDD by the NEP.

• comm_param_len: Number of parameters in comm_param.

• appl_data: Pointer to data saved by the EDD application.

• appl_free: Pointer to a function of the EDD application. When the connection is removed, the libgedd calls it to remove appl_data.

This structure describes communication parameters. It is used by both the NEP and EDD.

Syntax:

typedef struct {
char label[EDD_PARAM_LABLE_L+1];
char value[EDD_PARAM_VALUE_L+1];
}EDD_COMM_PARAM_ST

Public members:

• label: Label of the parameter.

• value: Value of the parameter.

This structure describes data used for the debugging process.

Syntax:

typedef struct {
char device[CMD_PROC_DEV_L+1];
char file_name[EDD_DEBUG_FNAME_L+1];
int type;
}EDD_DEBUG_MSG;

Public members:

• device: Device name that identifies the connection.

• file_name: File name that information is dumped into.

• type: Identifies the type of data to dump.

This structure describes information used by the generic driver in the NEP to manage the connections to the EDD.

Syntax:

typedef struct {
CS_CHAR socket_client;
CS_USHORT sa_family;
CS_CHAR host_name[EDD_HOST_NAME_L+1];
CS_CHAR host_ipaddr[EDD_HOST_IPADDR_L+1];
CS_USHORT port;
CS_CHAR *comm_params;
CS_INT len;
CS_INT write_timeout;
CS_BINARY *buffered_data;
CS_INT buf_len;
}GENERIC_SESS_DATA;

Public members:

• socket_client: Identifies whether the process is a server or a client from the socket.

• sa_family: Identifies the kind of socket.

• host_name: Remote host name the socket is connecting to.

• host_ipaddr: Remote host IP address.

• port: Remote port number.

• comm_params: Pointer to a buffer where the communication parameters are saved.

• len: Length of the communication parameter buffer.

• write_timeout: Time available for writing to the socket.

• buffered_data: Buffering data to be sent while the socket is not available.

• buf_len: Length of buffered_data.

The application uses the data types listed below to determine the state of a transaction and communication.

The EDD transaction involves the following processes:

• Connection process

• Disconnection process

• Forward data from the NEP to the NE

• Forward data from the NE to the NEP.

• Once the EDD is started, it opens the socket listening channel and waits for the connection request.

• The generic driver in the NEP sends the socket connection request to the EDD. Once the request is accepted, the generic driver sends the connection request for establishing a connection to the NE. This request has a data type EDD_CONNECT. The communication parameters saved in tbl_comm_param for this connection are transferred to the EDD at the same time.

• On receiving the NE connection request, the EDD saves the communication parameters in the format described by the structure EDD_COMM_PARAM_ST and passes the request to the EDD application.

• The EDD application establishes the connection to an NE identified by the communication parameters. An ACK (EDD_CONNECTED) or NACK (EDD_DISCONNECTED) is sent back to the generic driver by calling a routine in libgedd.

• If the connection is established successfully, it is put under the monitoring provided by one of the approaches.

• If the attempt of establishing a connection fails, a NACK is sent to the NEP and the socket connection to the NEP is closed.

• If the NEP initiates the disconnection process, the generic driver sends EDD_DISCONNECT to the EDD.

• On receiving the request, the EDD application is informed to close the connection to the NE. The application then sends EDD_DISCONNECTED to the NEP and closes the socket connection to the NEP.

• If the EDD initiates the disconnection process, usually due to a lost connection to the NE, it sends EDD_DISCONNECTED to the NEP and then closes the connection to the NEP.

• Connections to the NEP are being monitored constantly. Whenever an arrival of data from the NEP is detected, the EDD application is informed.

• The EDD application uses a routine in libgedd to retrieve the data.

• The EDD application forwards the data retrieved to a designated NE using the communication API.

• Connections to the NE are being monitored constantly. Whenever an arrival of data from an NE is detected, the EDD application is informed.

• The EDD application retrieves the data using the communication API.

• The EDD application calls a routine in libgedd to forward the data to the NEP.

This function allows the application to instruct the API to monitor a connection. An added connection is always a connection to the NE that has a corresponding connection to the NEP.

Syntax:

CS_VOID gedd_add_fd (CS_INT conn_idx, int fd)

Arguments:

• conn_idx: Identifies the connection to the NEP that the new file descriptor is related to.

• fd: The file descriptor to be added.

Return Values:

gedd_poll

See also gedd_api_disconnect_ack.

This function is called after the application successfully connects to an NE. If the NEP does not receive the confirmation in a certain period of time, the connection attempt fails. Since a connection to an NE is always related to a connection to the NEP, the identifier of the connection to the NEP is used as a reference.

Syntax:

CS_VOID gedd_api_connect_ack (CS_INT conn_idx)

Arguments:

• conn_idx: Identifies the connection to the NEP.

See also gedd_api_connect_ack.

This function is used in the following scenarios:

• The application calls this function to inform the NEP that establishing a connection with an NE has failed. The NEP tries to reestablish the connection and reprocess the incomplete task

• The application calls this function to confirm to an NEP that a disconnect request has completed (successful or failed).

• The application informs the NEP that it has just lost a connection to the NE. The NEP tries to reestablish the connection and reprocess the incomplete task

Syntax:

CS_VOID gedd_api_disconnect_ack(CS_INT conn_idx)

Arguments:

• conn_idx: Identifies the connection to NEP.

See also gedd_get_fd.

This function is only used for the Application Poll Approach and allows the application to retrieve data from the NEP. When the application detects event(s) from connections to the NEP, it must call this function to retrieve data. Based on the data type returned by this function, the application takes proper action.

The following lists the valid data types.

• edd_connect: NEP requests a connection to an NE.

• edd_accept: A new connection to the NEP is established. The application should get the related file descriptor.

• edd_disconnect: NEP requests to disconnect from an NE.

• edd_data: Data from the NEP is ready.

• edd_break_key: NEP requests to send a break to an NE.

• edd_option: NEP requests to send a option to an NE.

• edd_no_action: API internally accepts a connection. The application should ignore this event.

Syntax:

CS_VOID gedd_appl_poll_get_req(int fd, CS_INT *request, CS_BINARY *buf, CS_INT *len) 

Arguments:

• fd: File descriptor that has data.

• request: Returns the data type mentioned in the previous table.

• buf: Returns the data from the NEP.

• len: Returns the length of the data.

See also gedd_unblock_sigio, gedd_signal_get_req, gedd_sigio_occurred, and gedd_sigio_reset.

This function is only used for Signal Approach and blocks the signal SIGIO. The application uses this function to prevent signal interruption when it is processing data. It unblocks the signal when it starts to poll connections.

Syntax:

CS_VOID gedd_block_sigio(CS_VOID)

This function allows the application to retrieve the data it saved before using gedd_set_appl_data. This function and gedd_set_appl_data are used together for the application to save the data that is related to a connection.

See also "gedd_set_appl_data."

Syntax:

CS_VOID *gedd_get_appl_data (CS_INT conn_idx) 

Arguments:

• conn_idx: Identifies the connection to the NEP.

Return Values:

The data retrieved.

This function allows the application to access parameters defined in tbl_comm_param. The application uses these parameters to establish a connection to an NE. This function only returns parameters that relate to the specified connection. Since this function returns a pointer to the parameter, the application does not delete it.

Syntax:

CS_CHAR *gedd_get_conn_param( CS_INT conn_idx, CS_CHAR *label) 

Arguments:

• conn_idx: Identifies the connection to the NEP.

• label: Parameter label interested.

Return Values:

The value of the parameter.

This function allows the application to retrieve the file descriptor that identifies a connection to the NEP. This function is used only for the Application Poll Approach. This function must be used after a call to gedd_appl_poll_get_req returns data type EDD_ACCEPT. The application puts the file descriptor into its poll list.

See also "gedd_appl_poll_get_req."

Syntax:

int gedd_get_fd(CS_CHAR *buf, CS_INT len) q

Arguments:

• buf: The buffer returned by a call to gedd_appl_poll_get_req.

• len: The length of the data in the buf.

Return Values:

File descriptor.

This function is only used for the Application Poll Approach and allows the application to obtain the EDD listening-file-descriptor. The application must call this function after it calls gedd_init. It must then monitor it on behalf of the API.

See also gedd_init.

Syntax:

int gedd_get_listen_fd (CS_VOID) 

Return Values:

File descriptor.

This function is only used for the Poll Approach and allows the application to poll all connections to the NEP and NEs. The application calls this function whenever it finishes processing data and this function returns the next event. If it detects events, the application calls gedd_poll_get_req to retrieve data.

Syntax:

CS_INT gedd_poll(CS_INT timeout, CS_INT *conn_idx)

Arguments:

• timeout: Time in milliseconds that gedd_poll should wait for events. If a machine does not support milliseconds, it is rounded up to the nearest legal value available on the system. Possible values are:

  • 0 – Returns immediately

  • -1 – Waits until there is at least one event

• conn_idx: Connection identifier returned by gedd_poll. It identifies which connection receives events. This identifier is used in subsequent API calls.

Return Values:

• POLL_NE_CONNECT: Events from connection to NEs.

• POLL_NEP_CONNECT: Events from connection to the NEP.

• POLL_FAIL: System error.

• POLL_TIMEOUT: Specified time is expired while gedd_poll has not detected any event.

• POLL_HANGUP: One of connections hangs up.

This function is only used for the Poll Approach and allows the application to retrieve data from the NEP. The application must use it to retrieve data when a call to gedd_poll returns events. Based on the data type returned by this function, the application takes the appropriate action.

See also gedd_poll.

The valid data types are:

• edd_connect: NEP requests a connection to an NE.

• edd_disconnect: NEP requests to disconnect from an NE.

• edd_data: Data from the NEP is ready.

• edd_break_key: NEP requests to send a break to an NE.

• edd_option: NEP requests to send a option to an NE.

Syntax:

CS_VOID gedd_poll_get_req(int fd, CS_INT *request, 
CS_BINARY *buf, CS_INT *len) 

Arguments:

• fd: File descriptor that has data.

• request: Returns the data type mentioned in the previous table.

• buf: Returns the data from NEP.

• len: Returns the length of the data.

This function allows the application to send data to the NEP. If this function, the application disconnects the connection.

Syntax:

CS_INT gedd_send_to_nep (CS_INT conn_idx, CS_VOID *buf, CS_INT len) 

Arguments:

• conn_idx: Connection identifier.

• buf: Pointer to the data to be sent. The data can be either ASCII or binary as long as the NEP can handle it.

• len: The length of the data.

Return Values:

• cs_succeed: The data was successfully sent to the NEP.

• cs_fail: Either data cannot be delivered or allowed time has expired. It is set by IO_TIMEOUT in ASAP.cfg or default value of three minutes.

This function allows the application to save data related to a connection. When the application uses the function, it provides a free function that is used by the API to free up the memory at disconnection time.

See also "gedd_get_appl_data."

Syntax:

CS_VOID gedd_set_appl_data( CS_INT conn_idx, 
CS_VOID *appl_data, CS_VOID (*free_ap_data)(CS_VOID *appl_data))

Arguments:

• conn_idx: Identifies the connection.

• appl_data: The data the application wants to save.

• free_ap_data: The function pointer to the cleanup function. It is called when the connection is dropped.

This function allows the application to check whether a signal is delivered during a period of time.

See also gedd_sigio_reset, gedd_block_sigio, and gedd_unblock_sigio.

Syntax:

CS_INT gedd_sigio_occurred(CS_VOID)

Return Values:

• TRUE: There is a signal.

• FALSE: There is no signal.

This function resets the flag that is used by gedd_sigio_reset to determine if a signal has gone off.

See also "gedd_sigio_occurred," "gedd_block_sigio," and "gedd_unblock_sigio."

Syntax:

CS_VOID gedd_sigio_reset(CS_VOID)

This function is only used for the Signal Approach and allows the application to retrieve data from the NEP. Once the application has detected an interruption of SIGIO, it calls this function to retrieve data. Based on the data type returned, the application takes proper action.

See also gedd_block_sigio, gedd_unblock_sigio, gedd_sigio_occurred, and gedd_sigio_reset.

The valid data types are:

• edd_connect: NEP requests a connection to an NE.

• edd_disconnect: NEP requests to disconnect from an NE.

• edd_data: Data from NEP is ready.

• edd_break_key: NEP requests to send a break to an NE.

• edd_option: NEP requests to send a option to an NE.

• edd_no_option: API internally accepts a connection. The application should ignore this event.

Syntax:

CS_VOID gedd_signal_get_req (int fd, CS_INT *request, 
CS_BINARY *buf, CS_INT *len) 

Arguments:

• fd: File descriptor that has data.

• request: Returns the data type mentioned in the table.

• buf: Returns the data from the NEP.

• len: Returns the length of the data.

Return Values:

None

This function is only used for the Signal Approach and unblocks the signal SIGIO. Before the application starts to poll its connections to the NEs, it calls this function to unblock the signal SIGIO. When the poll function is interrupted by SIGIO, the application calls gedd_signal_get_req() to retrieve data.

See also "gedd_block_sigio," "gedd_signal_get_req," "gedd_sigio_occurred," and "gedd_sigio_reset."

Syntax:

CS_VOID gedd_unblock_sigio(CS_VOID) 

Arguments:

None

Return Values:

None

If the network API can convert a connection to the UNIX file descriptor, use the Poll Approach. For the Poll Approach, the application passes the file descriptor to libgedd after it has established a connection to an NE. The application call gedd_poll() monitors all connections.

If the network API can monitor the connections to the NEP on behalf of libgedd, you use the Application Poll Approach. For the Application Poll Approach, the application must monitor all connections including connections to the NEP. For this approach, the application uses APIs to retrieve data to and from the NEP.

For the Signal Approach, the application uses routines provided by the network API to monitor the connection to the NEs. When data is coming from the NEP, a UNIX signal, SIGIO, interrupts the monitoring. Once the monitoring is interrupted, the application calls routines provided by libgedd to retrieve the data.

The following examples outline how to implement the Signal, Poll and Application Poll Approach in the application. The examples highlight each approach, although you can use alternative ways.

Signal Approach:

/* application initialization */
void edd_ap_init(void)
{
   ...
   gedd_init( EDD_SIGNAL_TYPE ); /* signal approach */
   ...
}

void edd_ap_main(void)
{
   ...
   edd_ap_init();
   ...
   while( TRUE ){
gedd_unblock_sigio(); 
/* Any signal during the block period */
if( gedd_sigio_occurred() ){

gedd_sigio_reset();
cc = EDD_NEP_DATA_IN;

}
else{

alarm( 300 ); /* in case we missed a signal */
/* start to monitor connection to NE */
cc = edd_ap_wait();

}
/* we don't want to be interrupted */
gedd_block_sigio();
alarm(0);
switch( cc ){
case EDD_NEP_DATA_IN:

edd_ap_int_handler();
break;
case EDD_NE_DATA_IN:
edd_ap_receive();
break;
...
}

   }
   ...
}
void edd_ap_int_handler(void)
{
   ...
   /* get data from all connections they have data to be retrieved */
   while( gedd_signel_get_req( &request, &conn_idx, &buf, &len ) ){
switch( request ){
case EDD_CONNECT:

if( ( conn_id = edd_ap_connection( conn_idx ) )== FAIL ){
gedd_api_disconnect_ack( conn_idx );
else{

/* save conn_id & conn_idx together in "appl_data" */

edd_ap_save_conn_idx( conn_id, conn_idx );
gedd_api_connect_ack( conn_idx );
}
break;
case EDD_DISCONNECT:
/* disconnect from NE and inform the disconnection */
appl_data = gedd_get_appl_data( conn_idx );
edd_ap_disconnection( appl_data->conn_id );
gedd_api_disconnect_ack( conn_idx );
break;

case EDD_DATA:

/* send data to NE */
appl_data = gedd_get_appl_data( conn_idx );
edd_ap_send( appl_data->conn_id, buf, len );
break;

}
...
   }
   ...
}

void edd_ap_receive(void)
{
   ...
   /* this routine finds conn_idx first, then related conn_id */
   conn_idx = edd_ap_next_active_conn();
   appl_data = gedd_get_appl_data( conn_idx );
   edd_ap_retrieve_data( appl_data->conn_id, &buf, *len );
   /* send data to NEP */
   gedd_send_to_nep( conn_idx, buf, len );
   ...
} 

edd_ap_wait() must detect whether it is awakened by a signal or data coming over the connection from an NE. If it is a signal, gedd_process_nep_req must be called to handle the event. This function is also required to block the process even if there is no connection.

The EDD application must associate each connection it manages with the conn_idx that it receives when it is connecting. In the example, this is done using the following routines: edd_ap_save_conn_idx() and edd_ap_next_active_conn().

The alarm() function used in the example is necessary, because the SIGIO signal can go off at any time in between the statements, "else{" and "cc = edd_ap_wait". If the signal goes off in this period, the system can go into a dead lock.

In edd_ap_save_conn_idx, the gedd_set_appl_data function is used to save connection-related data.

Poll approach:

void edd_ap_init(void)
{
   ....
   gedd_init( EDD_POLL_TYPE ); /* poll approach */
   ...
}
void edd_ap_main(void)
{
   ...
   edd_ap_init();
   ...
   while( TRUE ){
/* monitor all connections */
cc = gedd_poll( POLL_BLOCK, &conn_idx );
switch( cc ){
/* where data comes from */

case POLL_NEP_CONNECT:
edd_ap_int_handler( conn_idx );
break;
case POLL_NE_CONNECT:
edd_ap_receive( conn_idx );
break;
...
}

   }
   ...
}

void edd_ap_int_handler( int conn_idx )
{
   ...
/* retrieve data from NEP */
      gedd_poll_get_req( conn_idx, &request, &buf, &len ) ){
      switch( request ){
      case EDD_CONNECT:
if( fd = edd_ap_connection( conn_idx, &conn_id ) == FAIL ){
gedd_disconnect_ack( conn_idx );
}
      else {
      /* passes file descriptor to libgedd */

gedd_add_fd( conn_idx, fd );
edd_ap_set_ap_data( conn_idx, conn_id );
gedd_connect_ack( conn_idx );
}
break;
case EDD_DISCONNECT:
appl_data = gedd_get_appl_data( conn_idx );
edd_ap_disconnection( appl_data->conn_id );
gedd_disconnect_ack( conn_idx );
break;
case EDD_DATA:
appl_data = gedd_get_appl_data( conn_idx );
edd_ap_send( appl_data->conn_id, buf, len );
break;

   }
   ...
}

void edd_ap_receive( int conn_idx )
{
   ...
   ap_data_st = ( AP_DATA_ST *)gedd_get_appl_data( conn_idx );
   edd_ap_retrieve_data( ap_data_st->conn_id, &buf, *len );
/* send data to NEP */
   gedd_send_to_nep( conn_idx, buf, len );
   ...
} 

The key difference between the routines above and the routines in the Signal Approach section is that the call to gedd_add_fd( conn_idx, fd ) right after the EDD application establishes the connection.

The conn_id, in the example, is a connection identifier used by a non-UNIX device API to access the connection to the NEs.

In this example, the programs calls edd_ap_set_ap_data() (it calls gedd_set_appl_data()) to save the API conn_id and other information into the array of EDD_INFO_ST. The gedd_get_appl_data() retrieves the conn_id back. In this approach, the application does not build a relationship between its connections and conn_idx, since it uses the conn_idx as an index to save and retrieve the information it needs. The libgedd takes care of the correlation among the connections.

Application poll approach:

void edd_ap_init(void)
{
   /* code here to do the application initialization */
....
   gedd_init( EDD_APPL_POLL_TYPE ); /* poll approach */
   
 /* pass fd to the application for monitoring */
   
   edd_add_fd(gedd_get_listen_fd());
   ...
}
void edd_ap_main(void)
{
   ...
   edd_ap_init();
   ...
   while( TRUE ){
/* monitor all connections */
cc = edd_ap_monitor(&fd);
switch( cc ){
/* check where data comes from and handle it */
case NEP_CONNECTION:

edd_ap_nep_data_handler( fd );
break;
case NE_CONNECTION:
edd_ap_ne_data_handler( fd );
break;
...
}

   }
   ...
}

void edd_ap_nep_data_handler( int fd )
{
   ...
/* retrieve data from NEP */
   gedd_appl_poll_nep_req( fd, &request, &buf, &len ) ){
   switch( request ){
   case EDD_ACCEPT:

new_fd = gedd_get_fd(buf, len);
/* code here to put fd in application poll list */
...
break;

case EDD_CONNECT:
   /* Connect to NE. Assume edd_ap_connection does all works such as puting new fd under monitoring and connecting to NE */

if ( edd_ap_connection( fd ) == FAIL ){

gedd_disconnect_ack( fd );

else {
gedd_connect_ack( fd );
}
break;

case EDD_DISCONNECT:
appl_data = gedd_get_appl_data( fd );
edd_ap_disconnection( appl_data );
gedd_disconnect_ack( fd );
break;

case EDD_DATA:
appl_data = gedd_get_appl_data( fd );
edd_ap_send( appl_data, buf, len );
break;

   }
   ...
}

void edd_ap_ne_data_handler( int fd )
{
   ...
/* retrieve data from NE */
   edd_ap_retrieve_data( fd, &buf, *len );

   /* get file descriptor for NEP here */
   ...
/* send data to NEP */
   gedd_send_to_nep( nep_fe, buf, len );
   ...
} 

The key difference between the above routines and the routines in other approaches is to retrieve the file descriptor and put it under the monitoring. The API does not monitor data from the NEP.

For the Application Poll Approach, the API uses the file descriptor as a connection identifier.

In this example, the program uses the appl_data to correlate connections. When a connection request is received, it should save the connection identifier to an NE into appl_data. The application can use other ways to do this.

Syntax:

The following is the syntax for an action function:

ACTION_STATUS action_func(CMD_PROC_DATA *data);

Input Parameters:

Each action function takes a pointer to the CMD_PROC_DATA structure as its argument. This data structure contains the following information:

• The ASDL parameters and variables generated in the State Table program before this action function is called.

• The communication variables for the device defined in the database table tbl_comm_param.

• The arguments passed to the action associated with this function in State Table program.

Return Values:

The action function returns ACTION_SUCCEED or ACTION_FAIL.

Use the ASAP API or database vendor routines to access databases.

Use system calls to access all resources available to the system. It is recommended that you check the ASAP and database vendor documents to find out whether similar routines are provided by the ASAP API and database vendor libraries.

Since the ASAP API is built on top of the database vendor and UNIX system libraries, and the database vendor API is built on the top of the UNIX system libraries, the ASAP API routine should be considered first, the database vendor API routine next, and the UNIX system routine last. For example, to move bytes from one location to another, the UNIX system call is memcpy(), the SYBASE API routine is srv_bmove() and the ASAP API routine is ASC_bmove() and should be used.

Most actions accept one or more arguments in their action strings. The action function associated with the action should retrieve and check those arguments first.

Use CMD_get_assignment() to retrieve ASCII variables or use CMD_get_bvar_assignment() to retrieve binary variables. These two routines return the arguments to caller by the structures as below for CMD_get_assignment():

typedef struct cmd_assignment_arg {
     struct cmd_assignment_arg *next;
    CS_CHAR value[VAR_STR_L+1];
} CMD_ASSIGNMENT_ARG;
typedef struct {
    CS_CHAR label[VAR_NAME_L+1];
    CS_INT num_fields;
    CMD_ASSIGNMENT_ARG *arg_list;
} CMD_ASSIGNMENT_BUF;
for CMD_get_bvar_assignment():
typedef struct cmd_bvar_assignment_arg {
    struct cmd_bvar_assignment_arg *next;
    CS_INT len;
    CS_CHAR label[VAR_NAME_L+1];
    VOIDPTR value;
} CMD_BVAR_ASSIGNMENT_ARG;
typedef struct {
    CS_CHAR label[VAR_NAME_L+1];
    CS_INT num_fields;
    CMD_BVAR_ASSIGNMENT_ARG *arg_list;
} CMD_BVAR_ASSIGNMENT_BUF;

To expand the action string without delimiters (for example, SEND ‘%DMS_CMD' 5), use CMD_expand_action_string() to retrieve the argument passed to action.

Check the number of arguments passed to the action function (see sample program) to ensure that subsequent operations will be accomplished successfully.

The ASDL parameters passed from the SARM and variables generated in the State Table program before the action function is called, may be accessed by the following routines. Once a variable is stored using CMD_store_var() and CMD_store_bvar(), it may be retrieved from this action function and the subsequent State Table program actions. Observe the following rules:

• Use CMD_get_var() to retrieve the parameters, ASCII variables and communication variables.

• Use CMD_store_var() to store the ASCII variables.

• Use CMD_get_bvar() to retrieve the binary variables.

• Use CMD_store_bvar() to store the binary variables.

Processing:

Call routines are provided by the ASAP, the database vendor, and UNIX library to process data.

An action function may exit in two conditions: ACTION_SUCCEED and ACTION_FAIL.

An action function must deallocate all spaces it has allocated before it exits. The routine CMD_free_assignment() is provided to deallocate the memory allocated by CMD_get_assignment().

Before an action function exits with a succeed status, it has to increase the variable PROGRAM_COUNTER by one in order to make the Interpreter proceed to the next action. The return statement will be:

return ACTION_SUCCEED;

When an action function exits with a failed status, the Interpreter will stop processing the rest of the actions in the State Table program. The return statement will be:

return ACTION_FAIL;

static ACTION_STATUS get_field_func(CMD_PROC_DATA *data)
{
    CMD_ASSIGNMENT_BUF *assign_buf;

CMD_ASSIGNMENT_ARG *rec_label, *field_name, *rtn_data;
RECORD_LIST *rec_list;
CS_CHAR ascii[BINARY_TO_ASCII_L+1];

    DBBINARY *record;
    CS_INT len;
    /* 
       The action associated with this function has format:

ACTION ‘%RTN=FIELD_A:%RTN_DATA` 

    */
    /* Retrieve action arguments */
    if ((assign_buf = CMD_get_assignment(data)) == NULL) {
/* Log event and trigger alarm */

CMD_EVENT (CMD_DBG_INFO, "SYS_ERR", __LINE__, __FILE__,
"%d State Table Error: Can't Expand Action String [%s]",
SRQ_ID, CUR_ACT_STRING);
/* Stop processing the state table program */
return ACTION_FAIL;

    }
    /* Check whether the number of arguments is correct */
    if (assign_buf->num_fields != NUM_GET_FIELD_ARGS) { 

CMD_DIAG(CMD_DBG_INFO, PROGRAM_LEVEL, "", __LINE__, __FILE__,
"Error: Not correct arguments for GET_FIELD");
CMD_free_assignment(assign_buf);
return ACTION_FAIL;

    }
    /* Pass arguments to variables which are easier to handle */
    rec_label = assign_buf->arg_list;
    field_name = rec_label->next;
    rtn_data = field_name->next;
    /* Pre-assign a return status to RTN */
    CMD_store_var(data, assign_buf->label, RTN_FAIL);
    /* Retrieve binary data saved under label rec_label->value */
    if (CMD_get_bvar(data, rec_label->value, (CS_VOID **)&record, 

&len, (CS_VOID **)&rec_list)!= SUCCEED) {
CMD_EVENT (CMD_DBG_INFO, "SYS_ERR", __LINE__, __FILE__,
"Error: Can't Provide Get Binary Variable ");

    }
    /* process data - application specific */
    /* Save data with the label rtn_data->value */
    else if (CMD_store_var(data, rtn_data->value, ascii) == FAIL) {

CMD_EVENT(CMD_DBG_INFO, "SYS_ERR", __LINE__, __FILE__,
"Error: Can't store [%s]", ascii);

    }
    else
/* Since every thing is OK, set RTN to succeed */

CMD_store_var(data, assign_buf->label, RTN_SUCCEED);

   
   /* It mandatory to remove space allocated by CMD_get_assignment */
    CMD_free_assignment(assign_buf);
    /* Increase the program counter by 1 */
    PROGRAM_COUNTER++;
    /* Action function is done successfully */
    return ACTION_SUCCEED;
}

You can specify a comment that is ignored by the Interpreter while processing the State Table. This comment is stored in the database and is helpful to document particular State Table functionality.

See also "COMMENT."

Java equivalent – Use // or /** style comments in Java source files.

Syntax:

# Comment String 

Example:

# This is a comment.

Used for the concatenation of binary and ASCII variables into a binary variable.

See also "CONCAT," LENGTH," "SUBSTR," "TRIM."

The last colon in the action string is used to specify the concatenation of a blank terminated string.

Syntax:

BCONCAT ‘%DEST=a1:a2:a3...:an:' 

Example:

1000 CONCAT ‘%DEST1=ABC:DEF'
1010 CONCAT ‘%DEST2=%BinaryVar1:%AsciiVar1'
1020 BCONCAT ‘%DEST=%DEST1:%DEST2'

To embed the colon character with BCONCAT, use ASCII variable and CONCAT until ":" character is attached. When the colon character is attached at the end of a string, use BCONCAT to make the final destination variable a variable of the binary type.

The SOLUTION for BCONCAT concatenation of two arguments with a colon character between is:

1000 CONCAT '%VAR10=ABC'
1001 CONCAT '%VAR11=DEF'
1002 CONCAT '%VAR12=%VAR10:%;:'
1003 BCONCAT '%FINAL=%VAR12:%VAR11'

Therefore, the final binary destination variable (FINAL) is a concatenation of two arguments with a colon character between them (ABC:DEF).

Evaluates the arithmetic expression in the action string and saves the numerical value in the result variable. The arithmetic expression can be formed with decimal number, specified as literal or string variables, and the following operators:

• +

• -

• *

• /

• (

• )

The order of preference of the above variables is:

• ( and )

• * and /

• + and -

The precision and scale of the output depends on the input. For example, the result of the expression (12.54 + 99.555) is 122.095. The result for the expression (555.55*-66) is -36666.30.

The result variable must be an ASAP Scalar variable and cannot be a Compound parameter. If no result variable exists, it is created and the result of the expression is saved in the variable. Any earlier value of a result variable is overwritten with the result of the expression.

Errors:

If the expression cannot be evaluated, due to mismatched brackets, undefined variables, etc., the action fails. This causes the associated ASDL to fail with an ASDL_STATE_TABLE_ERR status. The action function issues a SYS_ERR event.

Syntax:

CALC ‘%RES=<arithmetic expression>'

Example:

CALC ‘%RES=(%a * ((%b / %d) + %e))'

This action function executes a specific function within a State Table. The State Table is identified by the ASDL command to be executed, as well as the technology and software load of the NE to be provisioned. This indirect mapping (defined in tbl_nep_asdl_prog) is necessary to ensure that the correct version of the function is executed.

See also "CHAIN," "FUNCTION," "RETURN."

This action uses the asdl_cmd, technology, and software load to determine the State Table where this function resides. It then executes this function.

To use this function, the translation tables must be configured appropriately. In particular, the asdl_cmd must have a mapping to the relevant state table.

Java equivalent – Invoke the Java class.method directly as a regular function call.

Syntax:

CALL asdl_cmd::name 

Example:

BEGIN EXAMPLE_1
#
# Call a function from a State Table utilities library and
# then chain the main processing ASDL.
#
1000 CALL ‘UTILS_LIBRARY::RESET'
1010 CHAIN ‘PROCESS_DATA'
1020 ASDL_EXIT ‘SUCCEED'
END EXAMPLE_1
BEGIN UTILS_LIBRARY
#
# Library Function to reset variables
#
1000 FUNCTION ‘RESET'
1010 CLEAR ‘%TEST_VAR'
1020 RETURN ‘‘
END UTILS_LIBRARY
BEGIN PROCESS_DATA
#
1000 IF_THEN ‘%TEST_VAR DEFINED'
1010 CONCAT ‘%RESULT=%TEST_VAR'
1020 COMMENT ‘Do other processing'
1030 ENDIF ‘‘
1040 RETURN ‘‘
#
END PROCESS_DATA

Checks a value against the current SWITCH value. If the values are equal, a subroutine call is made to the specified function address at the action integer.

See also "DEFAULT," "SWITCH," "ENDSWITCH."

Java equivalent – Use Java switch statement.

Syntax:

CASE <expand string> function address

Example:

1000 SWITCH ‘%TMP'
1010 CASE ‘TEST' 2000
1020 CASE ‘%VAR1' 2500
1030 DEFAULT ‘‘5000
1040 ENDSWITCH ‘‘
1050 ASDL_EXIT ‘SUCCEED'
# Handle TEST Case
2000 CONCAT ‘%TMP1=1'
2010 RETURN ‘‘
# Handle Dynamic match of "%VAR1" and "%TMP"
2500 CONCAT ‘%TMP2=1'
2510 RETURN ‘‘
# Handle Default case of no match
5000 CONCAT ‘%TMP3=1'
5010 RETURN ‘‘

This action function is expanded to determine the ASDL command. The ASDL command is then used to determine which state table the Interpreter invokes.

See also "CALL," "FUNCTION," "RETURN."

It also uses the ASDL command in the expand string, technology, and software load to determine which state table to call. It then executes the state table.

The current state table is suspended until the chained state table completes.

To use the function, CHAIN, the translation tables must be configured appropriately. In particular, the ASDL must have a mapping to the relevant state table.

Java equivalent – Invoke the Java class.method directly as a regular function call.

Syntax:

CHAIN <expand string> 

Example:

1000 CHAIN ‘DMS_CHECK'

Sets the specified variable to NULL. It is the same as CONCAT “%variable=".

See also "CONCAT."

Java equivalent – Assign null to the variable.

Syntax:

CLEAR ‘%variable' 

This action function is expanded to determine the specified UNIX filename that is used to dump the Interpreter working data. This data includes all parameters currently set within the Interpreter.

Java equivalent – Implement custom command dumping functionality using java.io classes.

Syntax:

CMD_DUMP ‘<filename>‘ 

Example:

Sample output appears below.

sunen214@caribou /u/itg/TEST/APIAF/EXECUTION >cat dump_file.doc 
Command Processor FTP_DEV3 Data
Tech: DMS Software Version: BCS33 ASDL Command: A_CMD_DUMP_1 Port State: 1
Error       : 
ASDL Status : 0
Response    : 
Param Group : Undefined
Switch Value: 
Variable Count: 0 Stack Depth 0 Program Counter 0
SARM Notify Needed: 1Port: 400618b0 Message: 406bfd58 Stack: 406af548 Var_tbl: 40919e70 
Program Tbl: 4068f4b8, Current_Prog: 4068f4b8
Port Bind Dump
Device: FTP_DEV3 Pool SSTNDMS Line_type: F Command Prod Queue: 51
Vs Key: 0 Disabled: 0 Binded: 1 VS Qid: 56 Host: SSTNNBSCDS1 Sess Qid: 50
 
Variable Dump
Level 2 ASDL_CMD = [A_CMD_DUMP_1]
Level 2 DEVICE = [FTP_DEV3]
Level 1 DIAL_NO = []
Level 2 HOSTCLLI = [SSTNNBSCDS1]
Level 2 HOST_IPADDR = [<IP address>]
Level 2 HOST_NAME = [supra]
Level 0 HOST_PASSWORD = [<password>]
Level 2 HOST_USERID = [rtcenv20]
Level 1 IS_ROLLBACK = [NO]
Level 2 LOOPBACK_ON = [1]
Level 0 MCLI = [SSTNNBSCDS1]
Level 2 PORT = [21]
Level 2 SOFTWARE = [BCS33]
Level 2 SRQ_ID = [9]
Level 1 TECH = [DMS]
Level 2 WO_ID = [WO_CMD_DUMP_1]
 
Stack Trace
 
Active Program Dump
4068f4b8 A_CMD_DUMP_1 Action Tbl 406cf880 Count 2 Next 00000000

Copies all parameters from one Compound parameter to another. The parameter to the right of the equal sign must be defined and must be a Compound parameter. In the example, OLD.a and OLD.b are copied into the new parameters NEWER.a and NEWER.b respectively.

Errors:

If the source parameter is undefined or is not a Compound parameter, the action fails. The failure of the action causes the associated ASDL to fail with an ASDL_STATE_TABLE_ERR status. The action function also issues a SYS_ERR system event.

Syntax:

CMPND_COPY ‘%variable=%variable'

Example:

CMPND_COPY ‘%NEWER=%OLD'

Specifies a comment that is ignored by the Interpreter.

See also "# – Comment character."

Java equivalent – Use // or /** style comments in Java source files.

Syntax:

COMMENT ‘comment string' 

Example:

1000 COMMENT ‘This is a comment'

Concatenates the arguments into a value and then sets the destination variable to the new value. When it is necessary to append spaces to the end of a string, the action argument must be terminated with a colon. For example:

CONCAT ‘a1:a2: :'

See also "BCONCAT," "LENGTH," "SUBSTR," "TRIM."

Java equivalent – Use Java String or Byte classes.

Syntax:

CONCAT %dest=a1:a2:a3: 

Parameters:

• %dest: The destination variable name of the result of the concatenation.

• a1:a2:a3: Where a1 can be one of [%var | constant]. a2 and a3 are optional.

Example:

1000 CONCAT %TMP=ABC: :DEF
1010 CONCAT %TMP2=# Equivalent to CLEAR
1020 CONCAT %TMP3=%TMP:%TMP2:At the end
1030 CONCAT %TMP4=A:%;:B #results in A:B

The following table describes which built-in variables create reserved characters.

Copies a state table binary variable value to an ASCII variable.

Syntax:

COPY_TO_ASCII    ‘%Ret=%Bvar[:If_Conversion]'

Parameters:

• If_Conversion: If the value is 0, no conversion is done and source (Bvar) is copied to destination (Ret), as is (Binary copy).

  If the value is 1, the source is converted to ascii values and then copied to the destination (only printable characters are copied, and the rest are converted to ".")

Remarks:

• %BVar must be a binary variable.

• No restrictions are imposed on the size of %BVar value.

• If %Bvar value is truncated, the action function sets the State Table variable %ASC_INFO_VAR to "TRUNCATED"; otherwise, it sets it to its default value (the empty string). The variable %ASC_INFO_VAR may be used to test for the condition if the value has been truncated.

Errors:

In the event of any of the following errors, state table program execution fails immediately.

• Number of arguments is less than (%BVar is missing). The following error message is printed: ‘Missing Mandatory Parameters'.

• %BVar does not exist or is not a binary variable. The following error message is printed: ‘Var %BVar does not exist or is not a binary variable'.

Example:

100 BCONCAT ‘%N=1234'
110 COPY_TO_ASCII ‘%N1=%N'
120 COPY_TO_ASCII ‘%N2=%N:0'
130 COPY_TO_ASCII ‘%n3=%N:1'
140 IF_THEN ‘%ASC_INFO_VAR == ‘TRUNCATED'
150 CONCAT ‘%I=O'
160 END_IF ‘'

Decrements a variable within the State Table program by the value specified. If you do not specify a value, a default value of 1 is used.

See also INCREMENT.

Java equivalent – Use arithmetic functionality in Java programming language.

Syntax:

DECREMENT ‘%var' value

Example:

# Decrement INDEX by 1
1000 DECREMENT '%INDEX'
# Decrement VALUE by 5
1010 DECREMENT '%VALUE' 5

Defines a regular expression that can be matched with a call to EXPR_GOSUB.

See also "EXPR_GOSUB."

You can have many regular expressions defined and then use EXPR_GOSUB to call the function of the first match it finds. This is similar to the UNIX awk utility.

The term regular expression is used here in the same general sense as UNIX uses the term. For more information, refer to regexp in the UNIX documentation.

Regular expressions are stored in a linked list. When a new regular expression is added, it is appended to the end of the list. Traversal of the list is performed from the head of the list until a match is found.

Syntax:

DEF_REGEXPR ‘regular expression' function address

Example:

1000 DEF_REGEXPR ‘[A-Z].[A-Z]' 2000 # (e.g."A.A" or "ABC")
1010 EXPR_GOSUB ‘%BUF' 5000
# If value of %BUF is ‘C1F', EXPR_GOSUB will set program counter to 2000.
# If value of %BUF is null, EXPR_GOSUB will set program counter to 5000.

This action is a default processing action for a SWITCH statement when none of the cases is satisfied.

See also "ENDSWITCH," "SWITCH," "CASE."

If none of the cases you specify can be satisfied, a subroutine call is made to the function address that you specify.

Java equivalent – Use Java switch statement.

Syntax:

DEFAULT ‘ ' function address

Example:

1000 SWITCH ‘%TMP'
1010 CASE ‘TEST' 2000
1020 CASE ‘%VAR1' 2500
1030 DEFAULT ‘‘ 5000
1040 ENDSWITCH ‘‘
1050 ASDL_EXIT ‘SUCCEED'
# Handle TEST Case
2000 CONCAT ‘%TMP1=1'
2010 RETURN ‘‘
# Handle Dynamic match of "%VAR1" and "%TMP"
2500 CONCAT ‘%TMP2=1'
2510 RETURN ‘‘
# Handle Default case of no match
5000 CONCAT ‘%TMP3=1'
5010 RETURN ‘‘

Deletes the specified regular expression from the list of regular expressions. If the action string is empty, all regular expressions are deleted from the list.

See also "DEF_REGEXPR," "EXPR_GOSUB."

The term regular expression is used here in the same general sense as UNIX uses the term.

For more information, refer to regexp in the UNIX documentation.

Syntax:

DEL_REGEXPR ‘regular expression'

Example:

# Delete the regular expression ‘*.AB*'
1000 DEL_REGEXPR ‘*.AB*' 
# Delete all regular expressions
1010 DEL_REGEXPR ‘'

Writes the expanded action string to the application's diagnostic file as a message with diagnostic level DiagLevel. If DiagLevel: is skipped, the level is defaulted to LOW_LEVEL. The diagnostic string can have ‘:' within it. This action is useful for cases in which you want to log a message only to the diagnostic file, not to the database.

See also "EVENT."

Java equivalent – com.mslv.activation.server Class Diagnostic. The Class diagnostic can be used to log messages to the diagnostic file.

Syntax:

DIAG ‘DiagLevel:Diagnostic string' 

Example:

1000 DIAG ‘LOW:Invalid Remote NE %MCLI'
# Lines 1000 and 1010 are equivalent.
1010 DIAG ‘Invalid Remote NE %MCLI' 
1020 DIAG ‘SANE:NE: %MCLI SRQ: %SRQID'

Defines the section of the state table that is executed if a previous IF or ELSE_IF cannot be executed.

See also "IF_THEN," "ELSE_IF," "ENDIF."

This action is a logical construct that must match with corresponding IF_THEN or ELSE_IF, and ENDIF constructs.

To accomplish the jump to the end of the IF_THEN clause, the command processor inserts the reserved action __GOTO_ENDIF just before each ELSE. If you are debugging State Tables, this statement is apparent.

Java equivalent – Use Java if statement.

Syntax:

ELSE ‘‘

Example:

1000 IF_THEN ‘%TMP == "1"‘
1010 LOG ‘Test # 1 Complete'
1020 ELSE_IF ‘%TMP == "2"‘
1030 LOG ‘Test # 2 Complete'
1040 ELSE ‘‘
1050 LOG ‘Unknown Test Completion'
1060 ENDIF ‘‘

If the expression specified is True, the next state table instruction is executed. Otherwise, execution continues at the next ELSE_IF, ELSE, or ENDIF state table instruction.

See also "IF_THEN," "ELSE," "ENDIF."

This logical construct must match with corresponding IF and ENDIF constructs.

To accomplish the jump to the end of the IF clause, the command processor inserts the reserved action __GOTO_ENDIF just before each ELSE. If you are debugging state tables, this statement becomes apparent.

Java equivalent – Use Java if statement.

Syntax:

ELSE_IF ‘expression' 

Example:

1000 IF_THEN ‘%TMP == "1"'
1010 LOG ‘Test # 1 Complete'
1020 ELSE_IF ‘%TMP == "2"'
1030 LOG ‘Test # 2 Complete'
1040 ELSE ‘‘
1050 LOG ‘Unknown Test Completion'
1060 ENDIF ‘'

Defines the end of a block of IF_THEN, ELSE, and ELSE_IF.

See also "IF_THEN," "ELSE," "ELSE_IF."

This logical construct must match the corresponding IF or IF_THEN constructs.

Java equivalent – Use Java if statement.

Syntax:

ENDIF ‘'

Example:

1000 IF_THEN ‘%TMP == "1"'
1010 LOG ‘Test # 1 Complete'
1020 ELSE_IF ‘%TMP == "2"‘
1030 LOG ‘Test # 2 Complete'
1040 ELSE ‘'
1050 LOG ‘Unknown Test Completion'
1060 ENDIF ‘'

Marks the end of the SWITCH statement. A subroutine call made as a result of a CASE or DEFAULT statement returns to this point.

See also "CASE," "DEFAULT," "SWITCH."

This logical construct must match with a corresponding SWITCH construct.

Java equivalent – Use Java switch statement.

Syntax:

ENDSWITCH ‘'

Example:

1000 SWITCH ‘%TMP'
1010 CASE ‘TEST' 2000
1020 CASE ‘%VAR1' 2500
1030 DEFAULT ‘' 5000
1040 ENDSWITCH ‘'
1050 ASDL_EXIT ‘SUCCEED'
# Handle TEST Case
2000 CONCAT ‘%TMP1=1'
2010 RETURN ‘'
# Handle Dynamic match of "%VAR1" and "%TMP"
2500 CONCAT ‘%TMP2=1'
2510 RETURN ‘'
# Handle Default case of no match
5000 CONCAT ‘%TMP3=1'
5010 RETURN ‘'

Marks the end of a WHILE loop. Nested WHILE loops are not supported.

See also "WHILE."

Java equivalent – Use Java while statement.

Syntax:

ENDWHILE ‘'

Example:

1000 CONCAT ‘%I=1'
1010 WHILE ‘%I != "10"‘
1020 LOG ‘Loop iteration %I'
1030 INCREMENT ‘%I'
1040 ENDWHILE ‘'

Deprecated. Use "ASDL_EXIT."

You can log ASAP system events from inside a State Table.

See also "DIAG."

Java equivalent – com.mslv.activation.server Class EventLog. Class EventLog can be used to generate system events.

Syntax:

EVENT ‘Event:Event String'

The Event parameter must be the name of an event (maximum 8 characters) defined in the Control server, and the Event String parameter is used as the event text for the event (maximum 80 characters).

For more information on configuring events, refer to the ASAP System Administrator's Guide.

Deprecated. This action function is provided for backward compatibility only. Use "EXEC_RPC."

This is a more general purpose action than EXEC and must be used in any new State Table development instead of EXEC.

This action executes the function in the NEP database (NEP_USER and NEP_PASSWORD are used to determine the source of the STORED_PROC) as follows:

EXEC_RPC STORED_PROC @asdl="Current ASDL Command",

@tech = "Technology",
@sftwr_load = "Software Load",
@arg1 = arg1, ... @argn = argn

Only arg1, arg2, etc. arguments are acceptable.

Multiple columns and rows of data can be returned by the function. The following rules are used to store the variables for later use:

• Each row increments an index value by 1 starting at 1.

• For the first row, the column labels are used to set up parameters in a structure, for example, var.column1, var.column2, var.column3.

• For each row returned, including the first row, the column labels are used in conjunction with the current index to create an array of structures, for example, var[%index].column1, var[%index].column2.

  If the column label is NULL or '', a normal array element is created, for example, var[%index] and "var" is also assigned the value. In this case, "%var" is set to the value in the last row where column label is NULL or ''.

  Examples:

  var[1].column1 and var.column1    = value at row 1, column 1
  var[1].column2 and var.column2    = value at row 1, column 2
  var[1] and var = value at row 1, column 3 # if column 3 has no label
  var[2].column1 = value at row 2, column 1
  var[2].column2 = value at row 2, column 2
  var[2] = value at row 2, column 3 

This function can pass many parameters to the stored function. It can also retrieve many data rows and columns back from the stored function. These data rows and columns are stored as indexed parameters within the Interpreter.

The EXEC_RPC function can retrieve only one result set specified with a cursor variable in the stored function.

The stored functions to execute via EXEC_RPC should be defined as functions with the following first four parameters mandatory:

cursor_var CURSOR
asdl CHAR
tech CHAR
sftwr_load CHAR

Converting float data types can cause rounding errors. All data types are converted into characters.

Java equivalent – Use JDBC library to invoke functions.

Syntax:

EXEC_RPC ‘%var=STORED_PROC:arg1:.:argn' 

Example:

State table 1:
1000 EXEC_RPC '%X=SSP_get_dn_list:%MACH_CLLI:%LEN'
# dir_no dn_type
# 2531920SINGLE PARTY LINE
# 2531921MULTIPLE APPEARANCE DIRECTORY NUMBER
# 
# Results:
# X[1].dir_no = "2531920",
# X[1].dn_type = "SINGLE PARTY LINE",
# X[2].dir_no = "2531921",
# X[2].dn_type = "MULTIPLE APPEARANCE DIRECTORY NUMBER"


State Table 2:
1000 EXEC_RPC '%X=SSP_get_dn_list:%HOST_CLLI:%SITE:%FROM_LEN'
# X[1] = MCLI or 'UNKNOWN'



Stored function:
TYPE SSP_get_mcli_rt1 IS RECORD (
        tmp              VARCHAR2(255)
 );

TYPE SSP_get_mcli_1 IS REF CURSOR RETURN SSP_get_mcli_rt1;

CREATE OR REPLACE FUNCTION SSP_get_mcli(
RC1     IN OUT NepPkg.SSP_get_mcli_1,
asdl            CHAR ,
tech            CHAR ,
sftwr_load      CHAR ,
arg1            tbl_clli_len_ltg.host_clli%TYPE,
arg2            tbl_clli_len_ltg.site%TYPE,
arg3            tbl_clli_len_ltg.from_len%TYPE)
RETURN INTEGER
AS
StoO_selcnt     INTEGER;
StoO_error      INTEGER;
StoO_rowcnt     INTEGER;
StoO_errmsg     VARCHAR2(255);
tmp             VARCHAR2(128);
BEGIN
        BEGIN
                StoO_rowcnt := 0;
                StoO_selcnt := 0;
                StoO_error  := 0;
                SELECT   mach_clli
                INTO SSP_get_mcli.tmp
                FROM tbl_clli_len_ltg
                WHERE host_clli = SSP_get_mcli.arg1
                AND site = SSP_get_mcli.arg2
                AND SSP_get_mcli.arg3 >= from_len
                AND SSP_get_mcli.arg3 <= to_len;
                StoO_rowcnt := SQL%ROWCOUNT;
                EXCEPTION
                        WHEN OTHERS THEN
                                StoO_rowcnt := 0;
                                StoO_selcnt := 0;
                                StoO_error := SQLCODE;
        END;
        IF StoO_rowcnt = 0 THEN
                SSP_get_mcli.tmp :=  'UNKNOWN';
        END IF;
        StoO_rowcnt := 0;
        StoO_selcnt := 0;
        StoO_error  := 0;
        OPEN RC1 FOR
        SELECT  SSP_get_mcli.tmp
        FROM DUAL;
RETURN 0;
END

To improve the efficiency of database queries conducted by ASAP, the EXEC_RPC action function has been split into two groups: EXEC_RPC is used for database update/insert functionality and has a cursor and EXEC_RPCV is used for database queries and employs no cursor.

Syntax:

    EXEC_RPCV   '%DEST=SSP:arg1:.:argn'

where…

• DEST is the name of the return variable that holds the result from the stored procedure.

• SSP is the name of the stored procedure in the NEP database to execute.

• arg1...argn are the input paramters provided for use in the stored procedure.

Example (usage in a state table):

BEGIN ST1
......
100          EXEC_RPCV   '%R1=SSP_test:1:35'
110          LOG 'Stored procedure returned %R1'
......
500          ASDL_EXIT 'SUCCEED'
END ST1

In this sample, R1 holds the result. %R1 will log the result into tbl_srq_log.

The stored procedure declaration and definition for EXEC_RPCV is similar to EXEC_RPC. The difference is that the first parameter declared in stored procedures for EXEC_RPCV is an OUT (output variable) instead of a cursor variable.

The following is an example of a stored procedure in the NEP database:

CREATE OR REPLACE FUNCTION SSP_test(
retv    OUT VARCHAR2 ,
asdl            CHAR ,
tech            CHAR ,
sftwr_load      CHAR ,
op              VARCHAR2 ,
data            VARCHAR2)
RETURN INTEGER
AS
StoO_selcnt     INTEGER;
StoO_error      INTEGER;
StoO_rowcnt     INTEGER;
StoO_errmsg     VARCHAR2(255);
BEGIN
        StoO_rowcnt := 0;
        StoO_selcnt := 0;
        StoO_error  := 0;
        SSP_test.retv := TO_NUMBER(SSP_test.op) || TO_NUMBER(SSP_test.data);
        RETURN 0;
END SSP_test;
/

This sample stored procedure has the following parameters:

• retv OUT VARCHAR2: This return parameter will return the result (see R1 state table variable in the state table above). This should less than 256 characters.

• asdl CHAR: ASDL name (this is not provided through EXEC_RPCV state table action function, but passed internally to the stored procedure).

• tech CHAR: Technology (this is not provided through EXEC_RPCV state table action function, but passed internally to the stored procedure).

• sftwr_load CHAR: Software load (this is not provided through EXEC_RPCV state table action function, but passed internally to the stored procedure).

• op VARCHAR2: Optional input parameter 1.

• data VARCHAR2: Optional input parameter 2.

The first four parameters are mandatory. After these four parameters, optional parameters should be declared.

Note that the return result is assigned to the variable SSP_test.retv so that it can be retreived via %R1.

You do not need to provide optional parameters. In this case, the stored function appears as follows:

CREATE OR REPLACE FUNCTION SSP_test1(
retv    OUT VARCHAR2 ,
asdl            CHAR ,
tech            CHAR ,
sftwr_load      CHAR)
RETURN INTEGER
AS
StoO_selcnt     INTEGER;
StoO_error      INTEGER;
StoO_rowcnt     INTEGER;
StoO_errmsg     VARCHAR2(255);
BEGIN
        StoO_rowcnt := 0;
        StoO_selcnt := 0;
        StoO_error  := 0;
        SSP_test1.retv := 'This is the return result from SSP_test1 stored function.';
        RETURN 0;
END SSP_test1;
/
Only the mandatory parameters are declared. There are no optional parameters. In a State Table, EXEC_RPCV is executed as follows for this stored function:
BEGIN ST2
......
100          EXEC_RPCV   '%R2=SSP_test1'
110          LOG 'Stored procedure returned %R2'
......
500          ASDL_EXIT 'SUCCEED'
END ST2

The R2 variable in this State Table will have the following string after EXEC_RPCV is executed:

"This is the return result from SSP_test1 stored function".

Deprecated. Use "ASDL_EXIT."

The buffer is checked against all the regular expressions that have been defined using DEF_REGEXPR. If a match is found, a gosub is executed to the function specified by the expression. If no expression is found, the default function specified by this action is used to execute a gosub.

See also "GOSUB," "GOTO," "MAP_GOSUB," "RETURN."

Syntax:

EXPR_GOSUB ‘buf' function address

Parameters:

• buf: The buffer to be checked.

• function address: The default function address if no match is found in the buffer.

Example:

1000 DEF_REGEXPR ‘[A-Z].[A-Z].[0-9]' 2000 # (e.g. "A.AB3
or C1D77")
1030 EXPR_GOSUB ‘ %BUF' 5000
# If value of %BUF is ‘S.F.9', for example, EXPR_GOSUB will set program counter to 2000.
# If value of %BUF is null, EXPR_GOSUB will set program counter to 5000.

Defines a function in a State Table program. The function can be defined as part of a library or locally as part of the State Table program from which it is invoked. If invoked locally, the function must be defined after all the invocations.

See also "CALL," "CHAIN," "RETURN."

Syntax:

FUNCTION ‘name' 

Example:

BEGIN EXAMPLE_1
#
# Call a function from a State Table utilities library and
# then chain the main processing ASDL.
#
1000 CALL ‘UTILS_LIBRARY::RESET'
1010 CHAIN ‘PROCESS_DATA'
1020 asdl_EXIT ‘SUCCEED'
END EXAMPLE_1
BEGIN UTILS_LIBRARY
#
# Library Function to reset variables
#
1000 FUNCTION ‘RESET'
1010 CLEAR ‘%TEST_VAR'
1020 RETURN ‘'
END UTILS_LIBRARY
BEGIN PROCESS_DATA
#
1000 IF_THEN ‘%TEST_VAR DEFINED'
1010 CONCAT ‘%RESULT=%TEST_VAR'
1030 ENDIF ‘'
1040 RETURN ‘'
#
END PROCESS_DATA

Retrieves an array of regular expressions (specified by expr from the buffer (specified by buf).

See also "DEF_REGEXPR."

The array is built as follows: dest[1], dest[2], etc.

Syntax:

GET_REGEXPR ‘%dest=expr:buf' 

Example:

1000 CONCAT ‘%BUF=HOST 00 1 10 23 NEWC 10 1 23 01'
1010 GET_REGEXPR ‘%SITE=[A-Z][A-Z][A-Z][A-Z]:%BUF'
#
# SITE[1]= HOST, SITE[2] = NEWC

Makes a subroutine call to the function specified by the function address.

See also "EXPR_GOSUB," "GOTO," "MAP_GOSUB," "RETURN."

Java equivalent – Use Java language constructs to control program flow.

Syntax:

GOSUB ‘ ' function_address

Example:

1000 GOSUB ‘' 2000
# Continue Processing ...
#
# Subroutine 
#
2000 CONCAT ‘%TMP=1'
2010 RETURN ‘'

Goes to the function address you specify and continues executing.

See also "EXPR_GOSUB," "GOSUB," "MAP_GOSUB," "RETURN."

Java equivalent – Use Java language constructs to control program flow.

Syntax:

GOTO ‘ ‘ function address

Example:

1000 GOTO ‘' 2000
1010 CONCAT ‘%TMP=Executed Second'
2000 CONCAT ‘%TMP=Executed First.'
2010 RETURN ‘'

If the specified expression is True, a subroutine call is made to the specified line number. Otherwise, execution continues with the next state table instruction.

See also "IFDEF," "IFNDEF."

The IF_THEN action, similar to this action, does not perform a subroutine call.

Java equivalent – Use Java if statement.

Syntax:

IF ‘expression' line #

Example:

1000 IF ‘%TMP >= "TEST"' 2000
# Continue Processing ...
2000 LOG ‘This is Test %TMP'
2010 RETURN ‘'

If the specified expression is True, the next state table instruction executes. Otherwise, execution continues at the next ELSE_IF, ELSE or ENDIF state table instruction.

See also "ELSE," "ELSE_IF," "ENDIF."

An expression is defined as follows:

operator::= { ==, !=, <=, >=, <, >, NOT_NULL, IS_NULL, DEFINED, NOT_DEFINED}
expression ::= %var operator [{ %var | number | “string"}]

The maximum number size must be within the boundary of double precision.

The State Table interpreter compares the values of integers or real numbers if the contents of the both value1 and value2 are numbers in the IF_THEN value1 REL_OP value2. An example of numbers in this format are 123, 12.3, +123, -123.

If using the IF_THEN clause to compare IP addresses, keep in mind that only IPv4 addresses are supported. The '= =' comparison for IP addresses behaves as follows:

• the format of the IP address should be a.b.c.d. Formats such as 'a.b.c', 'a.b', 'a', 'a..b.c' are not supported.

• leading 0s are considered to be an octet. For example, if the IP address is 010.9.12.1, then 010 is considered to be an octet and the actual IP address is interpreted as 8.9.12.1. In other words, 010.9.12.1 does not equal 10.9.12.1.

• all digits that have leading 0s should be less than 8 since it is recoginzed as an octet. 089.20.1.195 is a malformed IP address which is consequently not recognized as an IP address.

• 10.001.24.196 and 10.1.24.196 are recognized as same IP address. Although though second part of first IP address "001" is considered as an octet and is therefore "1".

  Note:

  If the IP address is not valid, it is considered to be a string.

Java equivalent – Use Java if statement.

Syntax:

IF_THEN ‘expression' 

Example:

1000 IF_THEN ‘%TMP == "1"'
1020 LOG ‘Test # 1 Complete'
1030 ELSE_IF ‘%TMP == "2"‘
1040 LOG ‘Test # 2 Complete'
1050 ELSE ‘'
1060 LOG ‘Unknown Test Completion'
1070 ENDIF ‘'

Example for IP addresses:

1000 CONCAT ‘%TMP' = 10.1.9.125
1010 IF_THEN ‘%TMP == "10.1.9.125"' (returns true)
...
2000 IF_THEN ‘%TMP == "010.1.9.125"' (returns false)
2010 IF_THEN ‘%TMP == "10.1.09.125"' (returns false)

Checks the variable that you specify. If it is defined, the action makes a subroutine call to the function that you specify.

See also "IF," "IFNDEF."

Java equivalent – com.mslv.activation.jinterpreter Class JProcessor

Syntax:

IFDEF ‘%var' function address

Example:

1000 IFDEF ‘%TMP' 2000
1010 ...
2000 LOG ‘TMP Variable Defined.'
2010 RETURN ‘'

Checks the variable that you specify. If it is not defined, the action makes a subroutine call to the function that you specify.

See also "IF," "IFDEF."

Java equivalent – getAllParams. The getAllParams methods returns a java.util.Properties object which can test for existence with the getProperty method.

Syntax:

IFNDEF ‘%var' function address

Example:

1000 IFNDEF ‘%TMP' 2000
1010 ...
2000 LOG ‘TMP Variable Undefined.'
2010 RETURN ‘'

Increments a variable within the state table program by the specified value.

See also "DECREMENT."

Java equivalent – Use arithmetic functionality in Java programming language.

Syntax:

INCREMENT ‘%var' value

Example:

1000 INCREMENT ‘%INDEX'
# Increment INDEX by 1
1010 INCREMENT ‘%VALUE' 5
# Increment INDEX by 5

Concatenates the parameters specified by p1, p2, and p3 to generate the name of the variable to be retrieved. For example, %OPT=OPT:%OPT_IDX can be used to generate OPT1, OPT2, ..., OPTn.

See also "CONCAT."

Java equivalent – Use String classes to concatenate values.

Syntax:

IND_SET ‘%dest=p1:p2:p3' 

Example:

1000 CONCAT   ‘%IDX=3'
1005  CONCAT  ‘%ARRAY[3]=abc'
#
# These two statements are equivalent.
#
1010  CONCAT  ‘%TMP=%{ARRAY[%IDX]}'
1020  IND_SET  ‘%TMP=ARRAY[:%IDX:]'
# Value of variable TMP will be: ‘abc'.

Concatenates the parameters specified by p1, p2 and p3 and then sets the destination parameter to the length of the string (maximum 255 bytes). The optional parameters are p2 and p3.

See also "CONCAT," "SUBSTR," "TRIM."

Java equivalent – Use String classes to concatenate and determine length values.

Syntax:

LENGTH ‘%dest=p1:p2:p3' 

Example:

1000  CONCAT     ‘%TMP1=abc'
1010  CONCAT      ‘%TMP2=defg'
1020    CONCAT  ‘%TMP3=hijklm'
1020  LENGTH  ‘%LEN1=%TMP1:%TMP2:XX'
1030  LENGTH  ‘%LEN2=12:%TMP3:21'
In this example, LEN1 = 9 and LEN2 = 10.

Searches the specified map to locate a value. If the value is found, the subroutine specified by the MAP_OPTION action is called. If the value is not found, the default subroutine specified when the map was created, for example, NEW_MAP action is executed.

See also "MAP_OPTION," "NEW_MAP," "RETURN."

Java equivalent – Use Java Map interface and implementation classes to create and manipulate a custom map.

Syntax:

MAP_GOSUB ‘%mapname "%value"'

Example:

1000  NEW_MAP  ‘PARSER_MAP'   2000
1010  MAP_OPTION  ‘PARSER_MAP "LEN:"'   2100
1020  MAP_OPTION  ‘PARSER_MAP "TYPE:"'   2200
1030  MAP_OPTION  ‘PARSER_MAP "SNPA:"'   2300
1040  MAP_GOSUB  ‘PARSER_MAP "%PARSE_BUF"'

In this example, if %PARSE_BUF = "LEN", execution of the program continues from line 2100.

Specifies the subroutine to call when the specified option value is used with the MAP_GOSUB function.

See also "MAP_GOSUB," "NEW_MAP."

Java equivalent – Use Java Map interface and implementation classes to create and manipulate a custom map.

Syntax:

MAP_OPTION ‘%mapname "%value"' function address

Example:

1000  NEW_MAP  ‘PARSER_MAP'   2000
1010  MAP_OPTION  ‘PARSER_MAP "LEN:"'   2100
1020  MAP_OPTION  ‘PARSER_MAP "TYPE:"'   2200
1030  MAP_OPTION  ‘PARSER_MAP "SNPA:"'   2300
1040  MAP_GOSUB  ‘PARSER_MAP "%PARSE_BUF"'

Concatenates variables A1, ... A(n) and then applies the mask to the resulting string.

• source – String to which MASK string is applied to.

• destination – The resulting string after MASK operation.

• mask – A string that modifies the source according to next rules:

If the mask includes the following characters:

• x – Ignores source character (delete). It does not appear in the destination string.

• y – Copies a character from the source to the destination string.

• Any other character – Inserts that character from MASK into the destination string.

• Use \x or \y – Forces (inserts) an x or y from MASK into the destination strings.

Syntax:

MASK‘%DEST=%MASK:%A1:%A2:... :%An' 

Example:

If the parse string is ‘ABCDEF', the following MASKs produce the following results:

Each x and y in the MASK (not including the ones prefixed with a "\") map directly to a character in the source string. Therefore, the 4th "x" or "y" in the MASK determines the processing on the 4th character in the source, and so on.

Incorrect:

“yy yy yy" => AB CD EF

Correct:

yy yy yy => AB CD EF

If a value cannot be located in the map options, this action defines a new map within the state table and the default subroutine to be executed.

See also "MAP_GOSUB," "MAP_OPTION."

Java equivalent – Use Java Map interface and implementation classes to create and manipulate a custom map.

NEW_MAP ‘mapname' function address

Example:

1000  NEW_MAP  ‘PARSER_MAP'   2000
1010  MAP_OPTION  ‘PARSER_MAP "LEN:"'   2100
1020  MAP_OPTION  ‘PARSER_MAP "TYPE:"'   2200
1030  MAP_OPTION  ‘PARSER_MAP "SNPA:"'   2300
1040  MAP_GOSUB  ‘PARSER_MAP "%PARSE_BUF"'

Allows the size of the variable %VAR to be expanded to the length, LENGTH. The new expanded area will be filled with the argument character, CHARACTER. The value of the variable is preserved if the size of the expanded variable is greater than the current size. Otherwise, an error occurs.

See also "ZERO_PAD."

Syntax:

PAD_CHAR ‘%RTN=%VAR:LENGTH:CHARACTER'

Example:

1000 BCONCAT   ‘%DEST=Sample1:Sample2'
1010 PAD_CHAR   ‘%RTN=%DEST:%Length:0'

Deprecated. Use "WAIT."

Returns from a subroutine or state table chain.

See also "CALL," "CHAIN," "EXPR_GOSUB," "FUNCTION," "GOSUB," "MAP_GOSUB."

Java equvalent – Use Java language constructs to control program flow.

Syntax:

RETURN ‘  count

Parameters:

• count: Optional, default is 1. If the count is set, multiple returns can be executed at once. A count of 0 is equivalent to a count of 1.

  Note:

  The count value must be used with caution as this is the equivalent to using a GOTO by skipping return points on the stack.

Example:

1000  GOSUB  ‘'   2000
1010  Continue Processing ...
# Subroutine 
#
2000  CONCAT  ‘%TMP=1'
2010  RETURN  ‘'

Sets the destination variable to a substring of the source string of the length you specify and starting at the offset you specify.

See also "CONCAT," "LENGTH," "TRIM."

Java equivalent – Use Java String classes.

Syntax:

SUBSTR ‘%dest=%sr c:off:len' 

Parameters:

• %des t: The destination string variable name.

• %src: The source string variable name.

• off: The offset at which to begin the substring. The first character of the source string is offset at 0.

• len: The length of the substring.

Example:

1000  CONCAT  ‘%TMP=1234567890'
1010  SUBSTR  ‘%TMP1=%TMP:0:2'  # %TMP1 = 12
1020  SUBSTR  ‘%TMP2=%TMP:9:5'  # %TMP2 = 0

Sets the current switch value for the state table.

See also "CASE," "DEFAULT," "ENDSWITCH."

The use of curly braces is highly recommended when fully expanding variable names that include non-alphanumeric characters (especially dot “.", left bracket [, or right bracket ]) carrying special meaning.

Java equivalent – Use Java switch statement.

Syntax:

SWITCH ‘<expand string>'

Example:

1000  SWITCH  ‘%TMP'
1010    CASE  ‘TEST'  2000
1020    CASE  ‘%VAR1'  2500
1030    DEFAULT  ‘'  5000
1040  ENDSWITCH  ‘'
1050  ASDL_EXIT  ‘SUCCEED'
# Handle TEST Case
2000  CONCAT  ‘%TMP1=1'
2010  RETURN  ‘'
# Handle Dynamic match of "%VAR1" and "%TMP"
2500  CONCAT  ‘%TMP2=1'
2510  RETURN  ‘'
# Handle Default case of no match
5000  CONCAT  ‘%TMP3=1'
5010  RETURN  ‘'

Concatenates the parameters p1, p2, and p3 into a larger parameter and then trims the parameter based on the trim_flag. The trimmed result is stored in the destination variable.

See also "CONCAT," "LENGTH," "SUBSTR."

Java equivalent – Use Java String classes.

Syntax:

TRIM ‘%dest=p1:p2:p3' trim_flag

Parameters:

• %dest: Destination variable.

• p1, p2, p3: Parameters passed to this action. Optional parameters are p2 and p3.

• trim_flag: Can be set to indicate whether or not leading blanks, trailing blanks, or both must be stripped. Possible values are:

  • 0 – No trimming

  • 1 – Leading blanks trim

  • 2 – Trailing blanks trim

  • 3 – Leading and trailing blanks trim

Example:

# Trim leading and trailing blanks from TMP 
1000 TRIM  ‘%TMP=%TMP'  3
# Trim trailing blanks
1010  TRIM  ‘%TMP=%BUF:%XYZ'   2

Pauses the State Table execution for the time you specify in seconds. If the time is 0, it defaults to one second.

Java equivalent – Use java.lang.Thread.sleep.

Syntax:

CONCAT ‘%WTIME=15'
WAIT ‘%WTIME'

Example:

# WAIT State Table execution for 120 seconds.
1000 WAIT  ‘120  '

Starts a WHILE loop. If the expression is “True", State Table execution continues with the next State Table operation. If the expression is not true, the State Table execution resumes at the point following the ENDWHILE statement.

See also "ENDWHILE."

Java equivalent – Use Java while statement.

Syntax:

WHILE ‘expression' 

Example:

1000  CONCAT  ‘%I=1'
1010  WHILE  ‘%I != "10"‘
1020  LOG  ‘Loop iteration %I'
1030  INCREMENT   ‘%I'
1040  ENDWHILE  ‘‘

Specifies the state table variable label. The state table variable is retrieved and the numeric value is saved in the variable which is preceded with leading zeroes. The number of leading zeroes equals field length as specified - (minus) value length. For example:

See also "PAD_CHAR."

    ZERO_PAD ‘%NUM_VAR'  5

If the variable %NUM_VAR contains a numeric field 345, ZERO_PAD action causes the value 00345 to be saved in the NUM_VAR variable. The number of leading zeroes is 2 in this case. If NUM_VAR contains a value of 3, 00003 is stored.

If NUM_VAR contains 1234567, ZERO_PAD truncates the field to 12345. The action integer specifies the total field length. If the action integer is set to 0, the number of leading zeroes is defaulted to 1.

Syntax:

ZERO_PAD ‘variable label' field length

Adds a specified header into the message that is ready to be sent to an EDD, and is awaiting a header.

See also "MSGSEND."

Syntax:

ADD_HEADER ‘%RTN=%VAR:TYPE'

Parameters:

• %RTN: The return variable (either SUCCEED or FAIL).

• %VAR: The variable that includes a message. A header type that must be one of the following:

  • CONNECT

  • CONNECTED

  • CONNECT_FAIL

  • DISCONNECT

  • DISCONNECTED

  • DATA

  • NO_ACTION

  • BREAK_KEY

  • OPTION

  • DEBUG

  • DEBUG_DISCONN

Example:

1000 BCONCAT   ‘%MESSAGE=%MSG1:%MSG2:%MSG3'
1010 ADD_HEADER   ‘%RTN=%MESSAGE:DATA'
1020 MEGSEND   ‘%MESSAGE'
1030 MSGRECV   ‘%RTN=MESSAGE_ACK'

Converts the value of the numeric variable, %VAR, from ASCII data type to binary.

The maximum length of the ASCII variable must be:

• decimal – 10 characters or less

• octal – 11 characters or less

• hexadecimal – 8 characters or less

This action function does not issue error messages when there are invalid characters in the string for the specified base.

For octal conversion, within the limit of 2^32-1, the action function does not allow the string to have the 11th character specified because the code only checks for 10 characters regardless of the base.

Syntax:

ASC_TO_BIN ‘%RTN=%VAR:TYPE'

Parameters:

Example:

100  BCONCAT   '%MSG1=32'
110  BCONCAT   '%MSG2=37'
120  CONCAT   '%AsciiVar=49'
130  ASC_TO_BIN   '%RTN=%AsciiVar:D'
140  BCONCAT   '%MESSAGE=%MSG1:%MSG2:%AsciiVar'
150  MSGSEND   '%MESSAGE'

ASC_TO_BIN will cause %AsciiVar to have 31 which the binary equivalent of 49.

Used in State Table programs that access NEs to complete an ASDL command. The programs then return the appropriate error, classified by an error type, and an optional error description. ASDL exit types include:

• SUCCEED – Successful ASDL command execution.

• FAIL – Hard error.

• RETRY – An ASDL command failed, but retries.

• MAINTENANCE – An ASDL command failed because the NE is currently unavailable to receive provisioning requests.

• SOFT_FAIL – An ASDL command failed but processing continues; does not result in failure of the order.

• DELAYED_FAIL – An ASDL had failed during provisioning. The SARM skips any subsequent ASDL in the CSDL, continues provisioning at the next CSDL, and then fails the order.

• STOP – Stops the ASDL command from processing.

Refer to the ASAP Cartridge Development Guidefor more detailed descriptions of these base_types.

Java equivalent – setASDLExitType. Sets the exit type and returns from the function.

Syntax:

ASDL_EXIT ‘%ERR_TYPE:%ERR_DESC' 

Parameters:

• %ERR_TYPE: A required parameter. Specifies the error type for the ASDL command. This can be one of the base error types or a user-defined type created using the Enhanced Error Management functionality.

• %ERR_DESC: An optional parameter. Optional error description field that can be used to provide a descriptive message about the error that occurred.

Example 1:

1100  IF_THEN    ‘%ANALOG == "N"'
1110    CONCAT    ‘%OPTION=CDB'
1120    CHAIN    ‘M-SET_OPTION_ON'
1130  ENDIF    ‘'
1150  CONCAT    ‘%ERR_TYPE=U_FAIL1'
1160  CONCAT    ‘%ERR_DESC=Unable to add Feature 1001'
1170  ASDL_EXIT    ‘%ERR_TYPE:%ERR_DESC'

Example 2:

|
|
2000  CONCAT      '%msg=Fail adding 3 features for :%MOBILE_NUMBER:'
2010  CONCAT      '%msg=%msg: - Mobile number is invalid'
2020  LOG      '%msg'
2030  VS_SEND_RESP       ''
2040  ASDL_EXIT      'INVALID_NUMBER:%msg'

Converts the value of the binary variable, %VAR, from binary to a numeric ASCII value.

The maximum length of the ASCII variable must be:

• decimal – 10 characters or less

• octal – 11 characters or less

• hexadecimal – 8 characters or less

This action function does not issue error messages when there are invalid characters in the string for the specified base.

For octal conversion, within the limit of 2^32-1, the action function does not allow the string to have the 11th character specified because the code only checks for 10 characters regardless of the base.

See also ASC_TO_BIN, MSGRECV.

Syntax:

BIN_TO_ASC ‘%RTN=%VAR:TYPE'

Parameters:

Example:

1000  ASC_TO_BIN  ‘%RTN=%AsciiVariable:D'
1010  CONCAT  ‘%MESSAGE=%MSG1:VALUE=
       :%AsciiVariable:%MSG2'
1020  MSGSEND  ‘%MESSAGE'
1030  MSGRECV  ‘%RTN=MESSAGE_ACK:%Length'
1040  NVIS_PARSE  ‘%MESSAGE'
1050  BIN_TO_ASC  ‘%RTN:%AsciiVariable:D'

Clears the virtual screen.

See also "GET."

Syntax:

CLEAR_VS‘'

Deprecated.

Java equivalent – VirtualScreen class.

Retrieves data from the virtual screen at a specified location. If the data retrieved from the virtual screen does not match the specified value, it retries once every second for num_retries times.

ROW, COL, and LEN are required keywords. ROW and COL specify the screen location using (1,1) as the top left corner. The lower right corner of the screen is specified by the appropriate communication parameters in the device configuration, for instance 80, 24.

Relative screen row positioning is specified using C for the current row only, for example, C-1 in row implies the line above the current row.

It is also possible to use state table variables for ROW, COL, and LEN and wildcard matches are possible for ROW and COL. The wildcard character is “*".

If the GET action references areas outside of the virtual screen, it returns to the calling state table. Check the value returned by the GET action in the state tables.

Syntax:

GET‘ROW:row:COL:col:LEN:len:INT:retry_interval %var=value:' num_retries
OR
GET‘ROW:row:COL:col:LEN:len:%var=value:' num_retries

Parameters:

• ROW:row: The row number. Possible values are:

  • A number – For example, ROW:4:.

  • A relative location – For example, ROW:C-2: – two rows above the current one.

  • A variable – For example, ROW:%Row: – references the variable specified in %Row.

  • A wildcard – For example, for any row on the screen, specify ROW:*:. If wildcards are used, the search value must be specified.

• COL:col: The column number. Possible values are:

  • A number – For example, COL:4:.

  • A variable – For example, COL:%Col: – references the variable specified in %Col.

  • A wildcard – For example, for any column on the screen, specify COL:*:. If wildcards are used, the search value must be specified.

• LEN:len: The length of the field to be retrieved. Possible values are:

  • A number – For example, LEN:4:.

  • A variable – For example, LEN:%Len: –references the variable specified in %Len.

• %var: Specifies the NEP variable that stores the value read from the virtual screen. This variable is referenced in the State Table after the GET call.

• value: Specifies the value expected to be read. This value can be hard-coded or passed through a variable.

  If a value is not specified, the virtual screen is read and no checks are performed.

  The GET action retries for num_retries times in this case. If the value is not being specified, you must specify num_retries as 1 (the default).

  If wildcards are used as either the row or column specifiers, you must specify this value.

• INT:retry_interval: Optional function that specifies the time in seconds to wait between attempts.

• num_retries: The maximum number of retries. If a number is not specified, it defaults to 1.

For the state table to determine the coordinates at which a match was found (for instance, using wildcard matching), the GET action defines two reserved State Table variables. These variables specify the matching x and y coordinates. These are only created by the GET action in non-loopback mod e. Possible values are:

• VS_X_COORD: The column offset at which point a match was found.

• VS_Y_COORD: The row offset at which point a match was found.

Example:

# Search for "Journal File" at row %Row, col %Col and len %Len
1000   GET  ‘ROW:%Row:COL:%Col:LEN:%Len:%Var=Journal
     File' 5
# Search for "Journal File" anywhere on the current line
1010  GET    ‘ROW:C:COL:*:LEN:12:%Var=Journal File'  5
# Search for "Journal File" anywhere on the virtual screen
1020  GET    ‘ROW:*:COL:*:LEN:12:%Var=Journal File'  5
# Search for "Journal File" at row 10, col 1 and len 12
1030  GET     ‘ROW:10:COL:1:LEN:12:%Var=Journal File'  5
# Search for "IBM test user"
2000  CONCAT     '%Row=3'
2010  CONCAT     '%Len=13'
2020  GET     'ROW:%Row:COL:*:LEN:%Len:%prompt=IBM test user' 10
# Only reference the returned coordinates if not in Loopback Mode
2030  IF_THEN   '%LOOPBACK_ON == 0'
2040   DIAG   'SANE:[%prompt] Found @ (%VS_X_COORD, %VS_Y_COORD)'
2050  ENDIF   ''

Deprecated.

Deprecated.

Deprecated.

Retrieves a user-defined secure data entry.

See also "SET_SECUREDATA."

Syntax:

GET_SECUREDATA   '%RTN=%NAME'

Arguments:

• %RTN: The return value of the action function.

• %NAME: The name of the secure data entry used as a key to retrieve the encrypted data.

Deprecated.

Generates a miscellaneous message and transmits it as part of the NE history information to the SARM to be stored in the SARM database.

When logging a compound variable, the variable must appear in braces (as indicated in the example). Otherwise, only the first part of the variable is parsed.

Java equivalent – log method, JProcessor class. Generates an NE history log item.

Syntax:

LOG ‘<expand string>'

Example:

2030  CONCAT ‘%MSG=msg'
2330  LOG ‘Output Text = [%{MSG.msg_txt}]'

Deprecated.

Sends a binary message to the NE when the communication with the NE is message-based. The binary message must be built as per ASAP-NE protocol and saved in %BVAR prior to invoking this action.

See also "ADD_HEADER," "ASC_TO_BIN," "MSGRECV."

Java equivalent – write method. SocketConnection class.

Syntax:

MSGSEND ‘%RTN=%BVAR'

Example:

# Build a specific record and send it
1005 BUILD_MSG  '%LENGTH=%REC_TYPE:PACKET'
1010 IF_THEN  '%LENGTH < 1'
1020 CONCAT  '%ERR_MSG=BUILD_MSG Action Error'
1025 CALL  'SPACE_LIB::ERR_EXIT'
1030 ENDIF  ''
1040 MSGSEND  '%RTN=%PACKET'
1050 IF_THEN  '%RTN != "SUCCEED"'
1051 CONCAT  '%ERR_MSG=MSGSEND Failed'
1052 CALL  'SPACE_LIB::ERR_EXIT'
1070 ENDIF  ''

Receives binary messages from the NE when the communication with the NE is message-based. The binary message of length LEN is expected to be received from the NE and saved in %BVAR by this action. The length LEN can be specified using a hard-coded value or a variable can also be passed.

See also "BIN_TO_ASC," "MSGSEND."

Java equivalent – read method. SocketConnection class.

Syntax:

MSGRECV ‘%RTN=%BVAR:LEN' wait_time

Example:

# Recv Hdr msg for Request-Completion notification
# NOTE: The value of LEN is hardcoded to 12
1190  MSGRECV    '%RTN=PACKET:12'
1200  IF_THEN    '%RTN != "SUCCEED"'
1201  CONCAT    '%ERR_MSG=MSGRECV Failed for HDR_MSG'
1210  CALL    'SPACE_LIB::ERR_EXIT'
1220  ENDIF    ''
1230  EXTRACT_MSG    '%RTN=HDR_MSG:PACKET'
1240  IF_THEN    '%RTN != "SUCCEED"'
1241  CONCAT    '%ERR_MSG=EXTRACT_MSG Failed for HDR_MSG'
1250  CALL    'SPACE_LIB::ERR_EXIT'
1260  ENDIF    ''
# Recv CMD_RESP Msg and extract it
# NOTE: The value of LEN is saved in the variable %RET_PAYLOAD_LENGTH
1270  MSGRECV    '%RTN=PACKET:%RET_PAYLOAD_LENGTH'
1280  IF_THEN    '%RTN != "SUCCEED"'
1281  CONCAT    '%ERR_MSG=MSGRECV Failed for CMD_RESP_MSG'
1290  CALL    'SPACE_LIB::ERR_EXIT'
1300  ENDIF    ''

Parameters:

• %RTN: SUCCEED – If the action function was successful.

• %BVAR: Stores binary data.

• LEN: Amount of data to retrieve.

• wait_time: Number of seconds to wait. <0 = infinite wait

Deprecated.

Sets the parameter group field to be passed back on any information parameters generated within the State Table. The information parameters that are saved to the SARM database are associated with the specified parameter group in the database.

When querying the SARM for any generated information parameters, the SRP specifies this parameter group as part of the query criteria.

For instance, if you want to return multiple instances of the same data from the NEP State Tables to the SRP (such as configuration details on each of a number of trunk lines), then prior to calling SEND_CMPND, you must specify the parameter group for this instance using PARAM_GROUP. The SRP then queries on the information parameters using both the parameter group as well as the parameter labels.

See also "SEND_PARAM," "SEND_COMPND."

Java equivalent – setParamGroup method. JProcessor class. Sets a group identifier.

Syntax:

PARAM_GROUP ‘<expand string>'

Example:

1000  PARAM_GROUP    ‘GROUP1'
1010  SEND_PARAM    ‘PARM1 "TEST1" I'
1020  SEND_PARAM    ‘PARM1-A "TEST1A" I'
1030  ...
1040  PARAM_GROUP  ‘GROUP2'
1050  SEND_PARAM  ‘PARM2 "TEST2" I'
1060  SEND_PARAM  ‘PARM2-A "TEST2A" I'

Enables the response log for any data that is returned from the NE. It causes the Interpreter to open the NE History file for an SRQ. The file can be transmitted back to the SARM using the VS_SEND_RESP action.

Upon completion of an ASDL, the Interpreter removes this file regardless of whether its contents were transmitted back to the SARM or not.

See also "VS_COPY_RESP," "VS_GET_RESP," "VS_SEND_RESP," "VS_STOP_RESP."

Java equivalent – startResponselog method. TelnetConnection class.

Syntax:

RESPONSELOG ‘'

Example:

1000 RESPONSELOG ‘'
2000 VS_SEND_RESP

Sends the data represented in the virtual screen coordinates that you specify to the SARM as an NE response.

See also "RESPONSELOG," "VS_COPY_RESP," "VS_SEND_RESP," "VS_STOP_RESP."

Java equivalent – returnVirtualScreen method. TelnetConnection class.

Syntax:

SCREEN_RESP‘X1:Y1:X2:Y2'

This action string is expanded and then sent to the NE when the communication with the NE is terminal-based.

See also "SENDKEY."

Java equivalent – send method. TelnetConnection class.

Syntax:

SEND  ‘string'

Example:

# Send the NEW command to the NE with parameters $, NXX and LINE
1000 SEND ‘NEW $ %NXX%LINE' 
1010 SENDKEY ‘ENT'  # Send the "ENTER KEY" to apply the MML.

Transmits the specified CSDL, Global, Rollback or Information Compound parameters with the specified base name back to the SARM.

See also "SEND_PARAM," "PARAM_GROUP."

Java equivalent – returnCSDLParam, returnCompoundCSDLParam, returnGlobalParam, returnCompoundGlobalParam, returnInfoParam, returnCompoundInfoParam, returnRollbackParam, returnCompoundRollbackParam. JProcessor class. Returns parameters to SARM.

Syntax:

SEND_COMPND ‘basename flags, NOT_NULL'
SEND_COMPND ‘basename flags'

Parameters:

• basename: Identifies the basename for the Compound parameter.

• flags: A string that has one or more of the following values:

  • C – CSDL Parameter

  • G – Global SRQ Parameter

  • R – Rollback Log Parameter

  • I – Work Order Information Parameter

• NOT_NULL: Only variables that are NOT_NULL are sent to the SARM.

Example:

#
# Send Scalar parameters from LEN_HDR structure
#
1000  SEND_PARAM  ‘LEN_HDR.LEN "%LEN" RI'
1010  SEND_PARAM  ‘LEN_HDR.MCLI "%MCLI" RI'
#
# Send the entire LEN_HDR structure as a compound structure 
# Send Return and Information Parameters
#
1020  SEND_COMPND  ‘LEN_HDR RI'

Deprecated.

Sends a function key to an NE. Upon receiving a response, it delays for the sleep value (in seconds), that you specify. This action is applicable only if the communication with the NE is terminal-based.

See also "SEND."

sleep_value is an optional parameter; when no sleep_value is specified, a value of zero (seconds) is passed. The function key, BRK, ignores the sleep_value option after receiving a response from the switch. Otherwise, the sleep_value option is not ignored.

If the sleep value time interval is set to "-1", the action function will return without waiting for a response.

The following values are valid function keys.

Java equivalent – sendKey method. TelnetConnection class.

Syntax:

SENDKEY ‘function_key' sleep_value

Example:

#Send the MML to the switch, followed by the enter key to apply the command.
1000 SEND ‘NEW $ %NXX%LINE'
1010 SENDKEY ‘ENT' 1

Performs option negotiation with the peer end (NE) where the communications is client-server/peer based. This action is primarily used by the TELNET Interface to set telnet options. The names of the telnet options include:

Usage:

• 1 – to set option (ON)

• 0 – to unset Telnet option (OFF)

The following is the function that sets Telnet options:

CS_RETCODE Telnet_set_option(CMD_PROC_DATA *data, CS_CHAR *telnet_option, CS_CHAR *value)

The following is an example of case TELOPT_TTYPE:

   case TELOPT_TTYPE:
          if (option_value) {
              /* The scenario will be:
               *     . send "will TELOPT_TTYPE"
               *     . recv "do TELOPT_TTYPE"
               *     . recv "send TELOPT_TTYPE"
               *     . send "TELOPT_TTYPE is XXXX"
               */
     .
     .
     .
  
   else {
              /* The scenario will be:
               *     . send "wont TELOPT_TTYPE"
               *     . recv "dont TELOPT_TTYPE"
               */   

Telnet _set_option() converts value to integer. You cannot place plain text in the value argument of SETOPTION.

For more information on TELNET options, refer to the UNIX man pages.

The following State Table program provides an example of the TELOPT_ECHO option name to set the telnet session to stop echoing.

#%VALUE is 0 or 1
1005 CONCAT '%TE=TELOPT_ECHO'
1006 CONCAT '%OFF=0'
1011 SETOPTION '%SO=%TE:%OFF'

Java equivalent – setOption method. TelnetConnection class.

Syntax:

SETOPTION ‘%RTN=%LABEL:%VALUE' 

Sends the specified variable as a network element parameter to the SARM.

See also "SEND_COMPND," "PARAM_GROUP."

Java equivalent – returnCSDLParam, returnCompoundCSDLParam, returnGlobalParam, returnCompoundGlobalParam, returnInfoParam, returnCompoundInfoParam, returnRollbackParam, returnCompoundRollbackParam. JProcessor class. Returns parameters to SARM.

Syntax:

SEND_PARAM ‘label value flags' 

Parameters:

• label: The parameter name (Max. 80 characters).

• value: The variable or quoted string specifying the parameter. Use the escape character (‘\') when quotation characters (“ “) are used in a string value.

• flags: A string that has one of the following values:

  • C – CSDL Parameter (adds parameter to current CSDL).

  • G – Global SRQ Parameter (adds parameter to work order).

  • R – Rollback Log Parameter (reverses ASDL).

  • I – Work Order Information Parameter (sends data back to the SRP).

For more information, see SRP_asap_get_wo_param in the SRP Library of the ASAP API Reference).

Example:

#
# Send Scalar Parameters
#
# Send CSDL parameter
1000  SEND_PARAM  ‘CFN "%CFNDN" C'  
# Send a global parameter
1010  SEND_PARAM   ‘MDN_DEFINED "YES" G'    
# Send information parameter
1020  SEND_PARAM  ‘LEN_HDR.MCLI "%MCLI" I' 

Deprecated. Use "VS_SEND_RESP."

Updates or adds a user-defined secure data entry.

See also "GET_SECUREDATA."

Syntax:

SET_SECUREDATA ‘%RTN=%NAME:%VALUE'

Arguments:

• %RTN: Return value of the action function.

• %NAME: Data containing information that can be used as a key in the secure data storage.

• %VALUE: The data to be secured.

Deprecated.

Stops the logging of information from the NE and then copies the response log file to the filename that you specify. The pathname is preceded with the current $LOGDIR, for example, $LOGDIR/pathname.

See also "RESPONSELOG," "VS_GET_RESP," "VS_SEND_RESP," "VS_STOP_RESP."

Java equivalent – copyResponselog method. TelnetConnection class.

Syntax:

VS_COPY_RESP‘pathname' 

Example:

# Copy Switch history to sub-directory keyed by the SITE
# code using LEN number as the filename.
1000 VS_COPY_RESP ‘LEN%SITE/%LEN'
...

Copies the current response file to the NE history file. The specified pathname is preceded with the current $LOGDIR, for example, $LOGDIR/pathname.

See also "RESPONSELOG," "VS_COPY_RESP," "VS_SEND_RESP," "VS_STOP_RESP."

Java equivalent – loadResponselog method. TelnetConnection class.

Syntax:

VS_GET_RESP‘pathname'

Example:

# Copy data from the specified file to the switch history file.
2000  VS_GET_RESP  ‘LEN%SITE/%LEN'

Stops the logging of information from an NE and then sends the information to the SARM as switch history.

See also "RESPONSELOG," "VS_COPY_RESP," "VS_SEND_RESP," "VS_STOP_RESP."

Java equivalent – returnResponselog method. TelnetConnection class.

Syntax:

VS_SEND_RESP  ‘'

Example:

1000  RESPONSELOG   ‘'
2000  VS_SEND_RESP  ‘'

Similar to the VS_SEND_RESP action, this action stops the logging of information from the NE. However, VS_STOP_RESP does not send the information to the SARM as switch history, but rather as a closed response file that can be parsed/processed by the state table or any chained state table.

See also "RESPONSELOG," "VS_COPY_RESP," "VS_SEND_RESP," "VS_GET_RESP."

Java equivalent – stopResponselog method. TelnetConnection class.

Example:

1000 RESPONSELOG   ‘'
...
2000 VS_STOP_RESP  ‘'

Defines a tabular column field to be read at the specified offset and length. Up to 10 columns can be read at a time, as col # is used to identify the data register.

See also READ_ROW."

Syntax:

DEF_COLUMN ‘offset:length' col #

Parameters:

• offset: The offset at which the column starts. Starts at position 1. This parameter can be a variable.

• length: The length from offset at which the column ends. This parameter can be a variable.

• col #: The number of the data register for up to 10 columns (0-9).

Example:

900  CONCAT    ‘%START=6'
950  CONCAT    ‘%LEN=10'
1000  DEF_COLUMN    ‘1:10'  0
1010  DEF_COLUMN    ‘11:5'  1
1020  DEF_COLUMN    ‘%START:%LEN'  2

This example defines three columns:

1. Starts at position 1 and has a length of 10.

2. Starts at position 11 and has a length of 5.

3. Starts at position 6 and has a length of 10.

Goes to a mark that has been created in the file.

See also "SET_MARK."

Syntax:

GOTO_MARK ‘ ' mark #

Parameters:

• Mark #: The number of the mark to GOTO. A maximum of 10 marks (0-9) can be used.

Example:

1000  SET_MARK  ‘'  0
1010  READ_ITEM  ‘'
1020  Process Item
1030  GOTO_MARK  ‘'  0
1040  READ_TO_EOL  ‘'  3
1050  Reprocess using the whole line

From the current cursor position, this action reads a fixed-length field of sizes (bytes) or to the end of the line.

See also "READ_GROUP," "READ_ITEM," "READ_LAST," "READ_ROW," "READ_STRING," "READ_TO_EOL."

Syntax:

READ_FIXED ‘ ' size

Reads a group of count fields on the current line into the data registers. If the end of the line is reached before the required number of fields is retrieved, the remaining field is set to the NULL string. Valid value for count is 1-10.

See also "READ_FIXED," "READ_ITEM," "READ_LAST," "READ_ROW," "READ_STRING," "READ_TO_EOL."

Syntax:

READ_GROUP ‘ ' count

Example:

The following is the current line:
CWT 3WC AUL 2962986 LOD 2962987
If this code is executed:
1000    READ_GROUP  ‘' 4
The data registers would be:
_D0 = CWT, _D1 = 3WC, _D2 = AUL, _D3 = 2962986

Reads a field from the data file into register _D0 where the field is delimited by a space, tab, or new line. This state table action also performs an automatic line feed.

See also "READ_FIXED," "READ_LAST," "READ_ROW," "READ_STRING," "READ_TO_EOL."

Syntax:

READ_ITEM ‘ ' 

Reads to the last field in the current line.

See also "READ_FIXED," "READ_GROUP," "READ_ITEM," "READ_ROW," "READ_STRING," "READ_TO_EOL."

Syntax:

READ_LAST ‘ ' 

Reads a fixed-format table row, defined by the current column definition, into the data registers. For columns that do not exist in the row, the data register is set to the NULL string (" ").

See also "READ_FIXED," "READ_GROUP," "READ_ITEM," "READ_LAST," "READ_STRING," "READ_TO_EOL."

Syntax:

READ_ROW ‘ ' trim_flag

Parameters:

• trim_flag: Can be set to indicate whether or not leading blanks, trailing blanks, or both must be stripped. Possible values are:

  • 0 – No trimming

  • 1 – Leading blanks trim

  • 2 – Trailing blanks trim

  • 3 – Leading and trailing blanks trim

Reads a string of bytes into register _D0 up to one of the specified delimiters. If the end of the line is reached before one of the delimiters, _D0 is set to the NULL string, (" ") and the current file position remains unchanged.

See also "READ_FIXED," "READ_GROUP," "READ_ITEM," "READ_ROW," "READ_ROW," "READ_TO_EOL."

Syntax:

READ_STRING ‘delimiters' trim_flag

Parameters:

• delimiters: Specifies the delimiter to use in the read operation. Space is specified as ‘ " "'.

• trim_flag: Can be set to indicate whether or not leading blanks, trailing blanks, or both must be stripped. Possible values are listed in the following table.

  • 0 – No trimming

  • 1 – Leading blanks trim

  • 2 – Trailing blanks trim

  • 3 – Leading and trailing blanks trim

Reads all bytes from the current line position to the end of the line into register _D0.

See also "READ_FIXED," "READ_GROUP," "READ_ITEM," "READ_LAST," "READ_ROW," "READ_STRING."

Syntax:

READ_TO_EOL ‘ ' trim_flag

Parameters:

• trim_flag: Can be set to indicate whether or not leading blanks, trailing blanks, or both must be stripped. Possible values are:

  • 0 – No trimming

  • 1 – Leading blanks trim

  • 2 – Trailing blanks trim

  • 3 – Leading and trailing blanks trim

Resets the LAM file pointer to the beginning of the file.

Syntax:

RESET_FILE ‘ ' 

Marks a location in the file that can be used to move around in the file. You can define a maximum of 10 marks and all marks are initialized to point to the start of the file.

See also "GOTO_MARK."

Parameters:

• Mark #: The number of the mark to set (maximum 10). The mark numbers can range from 0 to 9.

Syntax:

SET_MARK ‘ ' mark #

Example:

1000  SET_MARK ‘'   0
1010  READ_ITEM ‘'
1020  Process Item
1030  GOTO_MARK ‘'   0
1040  READ_TO_EOL ‘'   3
1050  Reprocess using the whole line

Moves the current file position to a location that is an x number of items ahead of the current location. This action skips the end of the line.

See also "SKIP_LINES."

Syntax:

SKIP_ITEMS ‘ ' count

Moves the file pointer to the beginning of a line that is an x number of lines later in the file.

See also "SKIP_ITEMS."

A count value of 1 means to move to the next line in the file.

Syntax:

SKIP_LINES ‘ ' count

Moves the current file pointer to the location in the file before the last read operation.

See also "READ_FIXED," "READ_GROUP," "READ_ITEM," "READ_LAST," "READ_ROW," "READ_STRING," "READ_TO_EOL."

Syntax:

UNDO_READ ‘ ' 

This action causes the local file to be appended to the file on the remote server. If the remote file is not specified, then the remote file is the name of the local file name.

Syntax:

FTP_APPE    ‘%RETURN=LocalFileName:RemoteFileName'

Parameters:

• LocalFileName: Specifies the local file to append to the file on the remote server. Can be a literal value or a state table variable. Maximum length of the file name is 255 alphanumeric characters.

• RemoteFileName: Specifies the remote file to be appended on the remote server. Can be a literal value or a state table variable. Maximum length of the file name is 255 alphanumeric characters.

Return Values:

• SUCCEED: The local file is appended to the file on the remote server. %RETURN contains SUCCEED.

• FAIL: Action fails. %RETURN contains FAIL or an FTP-related error code.

See also FTP_SEND.

Example 1:

1010 FTP_APPE      '%RET=aaa:bbb'

Example 2:

1010 FTP_APPE      '%RET=/tmp/aaa:bbb'

Example 3:

1010 FTP_APPE      '%RET=aaa:/tmp/bbb'

Example 4:

1010 FTP_APPE      '%RET=/tmp/aaa:/tmp/bbb'

Example 5:

1010  CONCAT        '%LOC_FILE=aaa'
1020  CONCAT        '%REM_FILE=/tmp/bbb'
1030  FTP_APPE      '%RET=%LOC_FILE:%REM_FILE'

Example 6:

1010  FTP_APPE      '%RET=aaa'

This action causes the remote present working directory to be changed to the directory specified by the argument, directoryName. The directory name can be a full or partial path name.

See also "FTP_LCD" and "FTP_PWD."

Syntax:

FTP_CD  '%RETURN=directoryName'

Parameters:

• directoryName: Specifies the remote host directory to change to. Can be a literal value or a state table variable.

Return Values:

• SUCCEED: The current remote working directory is changed to the specified directory and the action succeeds. %RETURN contains SUCCEED.

• FAIL: Action fails. %RETURN contains FAIL or an FTP error code.

Example – Changing the current remote working directory:

1010  FTP_CD     '%RET=/hpdev/hpenv5/NE_RESPONSES'
1020  FTP_CD     '%RET=LOGS/980315'

The current remote working directory after line 1020 is:

 /hpdev/hpenv5/NE_RESPONSES/LOGS/980315.

This action causes the remote server working directory to be changed to the parent of the current remote server working directory.

See also "FTP_CD" and "FTP_LCD."

Syntax:

FTP_CDUP       ‘%RETURN'

Parameters:

None.

Return Values:

• SUCCEED: The remote server working directory is changed to the parent of the current remote server working directory. %RETURN contains SUCCEED.

• FAIL: Action fails. %RETURN contains FAIL or an FTP-related error code.

Example:

1010  FTP_CDUP      '%RET'

This action causes the file specified by fileName to be deleted from the remote NE host file system. fileName cannot contain a directory path name. The FTP_CD action is used first to change a remote current directory to the directory containing the file. This action fails if an error occurs, for example, the file does not exist.

See also "FTP_CD."

Syntax:

FTP_DELE  '%RETURN=fileName'

Parameters:

• fileName: Specifies the file name to be retrieved from the remote server. Can be a literal value or a state table variable.

Return Values:

• SUCCEED: Specified file is deleted from the remote server and the action succeeds. %RETURN contains SUCCEED.

• FAIL: Action fails. %RETURN contains FAIL or FTP-related error code.

Example 1 – Deleting a file located in the remote present working directory:

1010  CONCAT     '%FILE_NAME=NEResp.dat'
1020  FTP_DELE   '%FILE_NAME'

The NEResp.dat file located in a remote present working directory is deleted.

Example 2 – Deleting a file located in a non-current remote working directory:

1010  FTP_CD     '/hpdev/hpenv10/NE_FILES/NE_RESPONSES'
1030  FTP_DELE   'NEResp.dat'

The NEResp.dat file is deleted.

This action causes a listing of the directory contents of the directory, RemoteDir, on the remote server to be put into the local file, LocalFileName. If the local file name is not specified, then a default local file name, ftp_dir.out, in the current local working directory is chosen.

See also "FTP_LS," "FTP_CD," and "FTP_LCD."

Syntax:

FTP_DIR  ‘%RETURN=RemoteDir:LocalFileName'

Parameters:

• RemoteDir: Specifies the directory on the remote server to be listed. Can be a literal value or a state table variable.

• LocalFileName: Specifies the local file to store the listing of the contents of the directory on the remote server. Can be a literal value or a state table variable. Maximum length of the file name is 255 alphanumeric characters.

Return Values:

• SUCCEED: Listing of the directory on the remote server is stored in the local file. %RETURN contains SUCCEED.

• FAIL: Action fails. %RETURN contains FAIL or an FTP-related error code.

Example 1:

1010  FTP_DIR      '%RET=aaa*:bbb'

Example 2:

1010  FTP_DIR      '%RET=/tmp:bbb'

Example 3:

1010  FTP_DIR      '%RET=/tmp:/tmp/bbb'

Example 4:

1010  FTP_DIR      '%RET=-al:/tmp/bbb'

Example 5:

1010  FTP_DIR      '%RET=-alR:bbb'

Example 6:

1010  CONCAT       '%REM_DIR=/tmp'
1020  CONCAT       '%LOC_FILE=bbb'
1030  FTP_DIR      '%RET=%REM_DIR:%LOC_FILE'

Example 7:

1010  FTP_DIR      '%RET=-alR'

The listing is stored in the ftp_dir.out file in current local directory.

This action causes the local present working directory to be changed to the directory specified by the argument, directoryName. The directory name can be a full or partial path name. This action fails if an error occurs for example, directory does not exist.

See also "FTP_CD" and "FTP_PWD."

Syntax:

FTP_LCD  '%RETURN=directoryName'

Parameters:

• directoryName: Specifies the local host directory to change to. Can be a literal value or a state table variable.

Return Values:

• SUCCEED: The current local working directory is changed to the specified directory and the action succeeds. %RETURN contains SUCCEED.

• FAIL: Action fails. %RETURN contains FAIL or an FTP-related error code.

Example – Changing the local present working directory:

1010  FTP_LCD  '%RET=/hpdev/hpenv10/NE_RESPONSES' 
1020  FTP_LCD  '%RET=/LOGS/980315' 

The local present working directory after line 1020 is now:

/hpdev/hpenv10/NE_REPSONSES/LOGS/980315.

This action results in a listing of the directory contents of the directory, RemoteDir, on the remote server to be put into the local file, LocalFileName. If the local file name is not specified, then a default local file name, ftp_ls.out, in the current local working directory is chosen.

The listing is stored in the ftp_ls.out file in the current local directory.

See also "FTP_DIR," "FTP_CD," and "FTP_LCD."

Syntax:

• FTP_LS: ‘%RETURN=RemoteDir:LocalFileName'

Parameters:

• RemoteDir: Specifies the directory on the remote server to be listed. Can be a literal value or a state table variable.

• LocalFileName: Specifies the local file to store the listing of the contents of the directory on the remote server. Can be a literal value or a state table variable. Maximum length of the file name is 255 alphanumeric characters.

Return Values:

• SUCCEED: The listing of the directory on the remote server is stored in the local file. %RETURN contains SUCCEED.

• FAIL: Action fails. %RETURN contains FAIL or an FTP- error code.

Example 1:

1010  FTP_LS      '%RET=aaa*:bbb'

Example 2:

1010  FTP_LS      '%RET=/tmp:bbb'

Example 3:

1010  FTP_LS      '%RET=/tmp:/tmp/bbb'

Example 4:

1010  FTP_LS      '%RET=-al:/tmp/bbb'

Example 5:

1010  FTP_LS      '%RET=-alR:bbb'

Example 6:

1010  CONCAT       '%REM_DIR=/tmp'
1020  CONCAT       '%LOC_FILE=bbb'
1030  FTP_LS       '%RET=%REM_DIR:%LOC_FILE'

Example 7:

1010  FTP_LS       '%RET=-alR'

This action creates a new directory on the remote server. The directory name can be a full or partial path name.

Syntax:

FTP_MKDIR  ‘%RETURN=directoryName'

Parameters:

• directoryName: Specifies the remote host directory to create. It can be a literal value or a state table variable.

Return Values:

• SUCCEED: Specified directory is created. %RETURN contains SUCCEED.

• FAIL: Action fails. %RETURN contains FAIL or an FTP-related error code.

Example 1:

1010  FTP_CD     '%RET=/tmp'
1020  FTP_MKDIR  '%RET=sub_tmp'

Example 2:

1010  CONCAT     '%REM_DIR=sub_tmp'
1020  FTP_CD     '%RET=/tmp'
1030  FTP_MKDIR  '%RET=%REM_DIR'

Example 3:

1010  CONCAT     '%REM_DIR=/tmp/sub_tmp'
1020  FTP_MKDIR  '%RET=%REM_DIR'

This action causes the remote server to return to the Present Working Directory. If the action is successful, the state table variable, DirectoryName, is assigned the returned value. This action fails if an error occurs.

See also "FTP_CD" and "FTP_LCD."

Syntax:

FTP_PWD  '%RET=%DirectoryName'

Parameters:

• DirectoryName: An output parameter that contains the name of the remote present working directory. Can be a literal value or a state table variable.

Return Values:

• SUCCEED: Remote present working directory name is returned and the action succeeds. %RETURN contains SUCCEED.

• FAIL: Action fails. %RETURN contains FAIL or an FTP-related error code.

Example – Changing the remote present working directory:

1010  FTP_CD   '%RET=/hpdev/hpenv5/NE_RESPONSES' 
1020  FTP_PWD   '%RET=%DIR'

The variable DIR contains the value:

 ‘/hpdev/hpenv5/NE_RESPONSES'

This action causes the file specified by fileName to be retrieved from the remote NE host server. fileName cannot contain directory path name. The FTP_CD action can be used first to change the remote current directory to the directory where the file is present.

See also "FTP_SEND," "FTP_CD," and "FTP_LCD."

Syntax:

FTP_RECV  '%RETURN=fileName'

Parameters:

• fileName: Specifies the file name to be retrieved from the remote server. Can be a literal value or a state table variable.

Return Values:

• SUCCEED: The specified file is retrieved from the remote server and the action succeeds. %RETURN contains SUCCEED.

• FAIL: Action fails. %RETURN contains FAIL or an FTP error code.

Example 1 – Retrieving a file and storing it in a non-current local directory:

1010  RESPONSELOG    ''
1020  FTP_LCD        '%RET=/hpdev/hpenv5/NE_RESPONSES'
1030  CONCAT         '%FILE_NAME=NEResp.dat'
1040  FTP_RECV       '%RET=%FILE_NAME'

The NEResp.dat file is retrieved and stored in the NE_RESPONSES directory. The call to RESPONSELOG initiates the logging of FTP commands and the FTP server replies to be logged on as switch history. You can check the SARM table tbl_srq_log.

Example 2 – Retrieving a file located in a non-current remote working directory :

1010  FTP_CD     '%RET=NE_FILES/NE_RESPONSES'
1030  FTP_RECV   '%RET=NEResp.dat'

The NEResp.dat file is retrieved and stored in the local present working directory.

This action causes the file named from on the remote server to be renamed as to.

See also "FTP_CD" and "FTP_CDUP."

Syntax:

FTP_REN  ‘%RETURN=from:to'

Parameters:

• from: Specifies the old file name on the remote server. Can be a literal value or a state table variable.

• to: Specifies the new file name on the remote server. Can be a literal value or a state table variable.

Return Values:

• SUCCEED: The file on the remote server is renamed to the new file name. %RETURN contains SUCCEED.

• FAIL: Action fails. %RETURN contains FAIL or related FTP error code.

Example 1:

1010  FTP_REN      '%RET=aaa:bbb'

Example 2:

1010  CONCAT       '%FROM=aaa'
1020  CONCAT       '%TO=bbb'
1030  FTP_REN      '%RET=%FROM:%TO'

Example 3:

1010  CONCAT       '%FROM=aaa'
1020  FTP_REN      '%RET=%FROM:bbb'

Example 4:

1010  CONCAT       '%TO=bbb'
1020  FTP_REN      '%RET=aaa:%TO'

This action removes a directory on the remote server. The directory name can be a full or partial path name.

See also "FTP_MKDIR," "FTP_CD," "FTP_CDUP," and "FTP_PWD."

Syntax:

FTP_RMDIR      ‘%RETURN=directoryName'

Parameters:

• directoryName: Specifies the remote host directory to remove. Can be a literal value or a state table variable.

Return Values:

• SUCCEED: Specified directory is removed. %RETURN contains SUCCEED.

• FAIL: Action fails. %RETURN contains FAIL or an FTP-related error code.

Example 1:

1010  CONCAT        '%REM_DIR=/tmp/subtmp'
1020  FTP_RMDIR     '%RET=%REM_DIR'

Example 2:

1010  CONCAT     '%REM_DIR=sub_tmp'
1020  FTP_CD     '%RET=/tmp'
1030  FTP_RMDIR  '%RET=%REM_DIR'

This action function toggles storing of files on the local system with unique file names. If a file already exists with a name equal to the target local file name for FTP_RECV command, a .1 is appended to the name. If the resulting name matches another existing file, a .2 is appended to the original name. If this process exceeds .99, an error message is printed, and the transfer does not take place. The default value is off.

See also "FTP_RECV," "FTP_LS," and "FTP_DIR."

Syntax:

FTP_RUNIQUE       ‘%RETURN=RUNIQUE'

Parameters:

• RUNIQUE: Can be 0 or 1. Can be a literal value or a state table variable.

Return Values:

• SUCCEED: For the file transfer operations to be successful, local file names are unique. %RETURN contains SUCCEED.

• FAIL: Action fails. %RETURN contains FAIL or an FTP-related error code.

Example 1:

1020  FTP_RUNIQUE  '%RET=0'

Example 2:

1010  CONCAT  '%RUNIQUE=0'
1020  FTP_RUNIQUE  '%RET=%RUNIQUE'

Example 3:

1010  CONCAT  '%UNIQ=1'
1020  FTP_RUNIQUE  '%RET=%UNIQ'

This action causes the file specified by fileName to be sent to the remote NE host server. fileName cannot contain the directory path name. FTP_LCD can be used to change the local directory to where the file is currently located. This action fails if an error occurs, for example, if the file does not exist.

See also "FTP_RECV," "FTP_CD," "FTP_LCD," and "FTP_SUNIQUE."

Syntax:

FTP_SEND  '%RETURN=fileName'

Parameters:

• fileName: Specifies the file name to be transferred to the remote server. Can be a literal value or a state table variable.

Return Values:

• SUCCEED: The specified file is transferred to the remote server and the action succeeds. %RETURN contains SUCCEED.

• FAIL: Action fails. %RETURN contains FAIL or an FTP-related error code.

Example 1 – Transferring a file located in the present local directory:

1010  CONCAT     '%FILE_NAME=NEScript.dat'
1020  FTP_SEND   '%RET=%FILE_NAME'

The NEScript.dat file is sent and stored in the remote present working directory.

Example 2 – Transferring a file not present in the current working directory:

1010  FTP_LCD     '%RET=/hpdev/hpenv10/FTP' 
1020  FTP_SEND    '%RET=NEData'

The NEData file is sent and stored in the remote present working directory.

This action function toggles the storing of files on the remote system with unique file names. The remote FTP server must support the STOU command for successful completion. The remote FTP server will report the unique name. If a file already exists with a name equal to the target local file name for FTP_SEND command, a .1 is appended to the name. If the resulting name matches another existing file, a .2 is appended to the original name. If this process exceeds .99, an error message is printed, and the transfer does not take place. The default value is Off.

See also "FTP_SEND."

Syntax:

FTP_SUNIQUE     ‘%RETURN=SUNIQUE'

Parameters:

• SUNIQUE: Can be 0 or 1. SUNIQUE can be a literal value or a state table variable.

Return Values:

• SUCCEED: For the file transfer send operations to be successful, remote file names are unique. %RETURN contains SUCCEED.

• FAIL: Action fails. %RETURN contains FAIL or an FTP-related error code.

Example 1:

1020  FTP_SUNIQUE  '%RET=0'

Example 2:

1010  CONCAT  '%SUNIQUE=0'
1020  FTP_SUNIQUE  '%RET=%SUNIQUE'

Example 3:

1010  CONCAT  '%UNIQ=1'
1020  FTP_SUNIQUE  '%RET=%UNIQ'

Opens the file whose pathname is stored in the NAME variable. It returns a file handler in the FH variable. You can set the default directory by setting the variable FILE_DEFAULT_DIR in the ASAP.cfg file. If the variable is not defined in the ASAP.cfg file, the present directory is the default directory. For example, if you set the first argument of the action function to file_name, then the file_name file is searched in "./" directory.

You are responsible for opening the file in a proper mode. You can get unpredictable results by opening a binary file in ASCII mode or opening an ASCII file in a binary mode.

Syntax:

OPEN_FILE '%FH= %NAME:%MODE'

Parameters:

• FH: Contains the file handle of the file whose name is stored in NAME variable.

• NAME: Variable contains the absolute full path name of the file.

• MODE: Contains the file open mode. The following is a list of file modes:

  • r – Opens the ASCII file with read-only permission.

  • rb – Opens the binary file with read-only permission.

  • w – Truncates the ASCII file to zero length or create for writing.

  • wb – Truncates the binary file to zero length or create for writing.

  • a+ – Opens or creates an ASCII file for update at end-of-file. You can also read the file in this mode.

  • ab+ – Opens or creates a binary file for update at end-of-file.

Return Values:

• SUCCESS: A file handler is returned in the FH variable.

• FAILURE: The ASDL fails.

Reads from a file that is represented by the file handler.

ASCII File:

To use the action function, READ_FILE, you must open the file in ASCII mode. The action function reads lines or characters from an ASCII file to ASCII variables. The first argument contains the file handler. The second argument represents the variable name that holds characters.

The function returns the number of bytes read from the file. You have the option to place ALL in the third argument. The READ_FILE then attempts to read the total file. If you place a positive number as the third argument, then the READ_FILE reads the number of bytes from the file indicated by the number. If the data length is larger than 254 bytes, it is split to a set of 254 byte long strings. These strings are stored in a set of variables, RBUF_1, RBUF_2, RBUF_3, … RBUF_n.

RBUF is the name of the base variable obtained from the second argument of the action string. While reading a file, the empty lines (only one new line character) is ignored by the action function. If reading only one line, the action ignores multiple empty lines. The action keeps reading the file until it reads a line with characters or encounters the end of the file.

Binary File:

To use the action function, READ_FILE, you must open the file in binary mode. The action function reads bytes from a binary file to binary variables. The first argument contains the file handler. The second argument represents the variable name that holds the data.

The function returns the number of bytes read from the file. RBUF is the name of the base variable obtained from the second argument of the action string.

For more information, see the OPEN_FILE action description.

Syntax:

READ_FILE '%RTN=%FH:%RBUF:[%OPTION]'

Parameters:

• RTN: Contains the number of bytes read from the file. If RTN = 0, the end of file is reached.

• FH: Contains the file handler that is obtained with OPEN_FILE action function.

• RBUF: Contains the name of a variable that stores bytes read from the file that has the file handle in the %FH variable. The name of the variable can be stored in %RBUF. If "%" is not prefixed before RBUF, then RBUF is treated as the name of the variable.

ASCII File:

This is an optional parameter. The parameter can have positive numbers or a string, ALL. If a positive number is defined through the argument, the number represents the number of bytes to be read from the file. If more than 254 bytes are read, the action function splits the data to multiple segments of 254 bytes and stores them in ASCII variables. However, if the read from the file is not larger than 254 bytes, the data is stored in one ASCII variable. For multiple variables, all (except the last variable) contain a string of 254 bytes long. If the parameter is not defined, then all characters of a line (excluding the new line character) are read to a variable. In case a line is more than 254 bytes, the characters read from the file are broken into 254-byte segments.

RTN contains the total number of bytes read. If ALL is defined in the OPTION variable, the file is read and stored in multiple ASCII variables. RTN returns the number of bytes read.

Binary File:

This is an optional parameter. The parameter can have positive numbers or a string, ALL. If a positive number is defined through the argument, the number represents the number of bytes to be read from the file. RTN returns a positive number to show number of bytes read. It returns 0 to indicate the end of a file. If you set ALL as an option, the file is read in the default mode (without the option argument). The default option is to store the file in one variable.

Return Values:

• SUCCESS: The number of bytes read is returned in the RTN variable.The RTN variable 0 means you have reached the end of the file for an ASCII file.

• FAILURE: The ASDL fails.

Example 1 (ASCII File):

READ_FILE  '%RTN =  %FH:RBUF'

READ_FILE reads bytes (up to a new line character) from the file (pointed to by file handler, %FH) and stores the data in the variable "RBUF". If the data length is larger than 254 bytes, but less than (2 x 254 + 1) = 509 bytes, then two variables contain the data.

The first part of the data is stored in RBUF_0 and the rest is stored in RBUF_1. If the data length is less than or equal to 254 bytes, the data is stored in the RBUF_0 variable. RTN returns the total number of bytes read.

Example 2 (ASCII File):

READ_FILE  '%RTN =  %FH:%RBUF'

If FILE_NAME is stored in the variable %RBUF, the READ_FILE reads bytes from the file (pointed by the file handle in %FH) until a new line character is encountered and stores the data in variable FILE_NAME.

Example 3 (ASCII File):

READ_FILE '%RTN = %FH:RBUF:500'

The READ_FILE reads 500 characters from the file (pointed to by file handler, %FH) and stores them in variable(s) that have a base name of RBUF. If the file is smaller than 255 characters, the file is stored in the RBUF_0 variable. If the file is larger than 254 characters but less than 509 characters, then two variables stores the data. The first part of the data is stored in RBUF_0 and the following is stored in RBUF_1. In this case, the RTN returns the total number of bytes read.

Example 4 (ASCII File):

READ_FILE '%RTN = %FH:RBUF:ALL'

The READ_FILE reads the whole file (pointed to by file handler, %FH) and stores it over a set of variables that has a base name of RBUF. RTN returns the total number of bytes read. If the file is smaller than 255 characters, then the file is stored in one variable. If the file is larger than 254 characters, then multiple variables contain the bytes from the file.

Example 5 (Binary File):

READ_FILE '%RTN = %FH:RBUF'

The READ_FILE reads the total file (pointed to by file handler, %FH) and stores it to the variable RBUF. RTN returns the number bytes read.

Example 6 (Binary File):

READ_FILE '%RTN = %FH:RBUF:100'

If the file length is less than or equal to 100 bytes, then RBUF contains the whole file and RTN returns the number of bytes read. If the file is larger than 100 bytes, then RBUF and RTN contain 100 bytes.

ASCII File:

To use the action function, WRITE_FILE, you must open the file in ASCII mode. The action function writes ASCII variables to a file. The first argument is a file handler for the file. The second argument contains the base name of variables that contain strings.

If the second argument is not prefixed with %, then the argument is treated as a string and is written to the file. If the third argument is set to FLUSH, then the function attempts to flush on write to the file. Writing to the file in such case depends on how the system sets the buffer default size. If the argument is set to COMPOUND, the action function attempts to write all variables to the file. If no option is defined, the action writes one variable specified in the second argument without flushing.

You can place the following control characters

• \t – Tab

• \v – Vertical tab

• \r – Carriage return

• \n – New line

• \f – Form feed. All other control characters have no effect on the action string.

Binary File:

For more information, see the "OPEN_FILE" action description.

To use the action function, WRITE_FILE, you must open the file in binary mode. The action function writes binary variables to a file. The first argument is a file handler for the file. The second argument contains the base name of variables that contain data to be written to the file. If the second argument is not prefixed with %, then the action function fails.

If you place COMPOUND in the third argument, the action writes all variables that are prefixed with the base name. The FLUSH option is similar to the one described for the ASCII file.

Syntax:

WRITE_FILE '%RTN=%FH:%WBUF:[%WOPTION]'

Parameters:

• RTN: Returns the number of bytes written to the file.

• FH: Contains the file handle created by the OPEN_FILE action.

• WBUF: Contains the name of a variable with data that needs to be written to the file. The name can be stored in %WBUF. If % is not prefixed before WBUF, the WBUF is treated as a string and is written to the file. If you enter ABC\n as the second argument instead of %WBUF, then ABC\n is written to the file. The new line character is \n.

This is an optional variable. If you set this argument to FLUSH, the action function writes a variable to the file and flushes it. If the argument is set to COMPOUND, the function writes contents to the file of all variables in the variable tree that has a base name contained in %WBUF. For example, if WOPTION is set to COMPOUND and the base name is WBUF, then the WRITE_FILE action function attempts to read WBUF_1, WBUF_2, … WBUF_n variables from the variable tree and writes them to the file.

Additional variables can be added as long as base name WBUF is prefixed in the variable name. For example, WBUF[1], WBUF.1 is written to the file if COMPOUND is defined. If the optional variable is not defined, the action writes one variable specified in the %WBUF variable.

Return Values:

• SUCCESS: The number of bytes written is returned in the RTN variable. If the RTN variable is '0', then no variable is available to write to the file.

• FAILURE: The ASDL fails.

The WRITE_FILE action follows the Compound parameter behavior. If the base name is ABC, then the action function writes contents of all variables that are prefixed by ABC. If you have ABCC, ABCD and a set of variables (from the READ_FILE action) ABC_1, ABC_2, … ABC_n, then the WRITE_FILE writes these variables to a file. If you want to write all variables from the READ_FILE action, then the base name must be changed to ABC_.

The order of the variables to be written to the file is based on ASCII value of the trailing characters.

Closes the file related to the file handler contained in %FH.

Syntax:

CLOSE_FILE  %FH 

Parameters:

• FH: Contains the file handler of the file to be closed.

Return Values:

• SUCCESS: Closes the file represented by the file handler.

• FAILURE: The ASDL fails.

Deletes the file.

Syntax:

DEL_FILE  %NAME 

Parameters:

• NAME: Contains the file name that must be deleted.

Return Values:

• SUCCESS: Removes the file.

• FAILURE: The ASDL fails.

  Note:

  The file must be closed before the action DEL_FILE is called. You can open the same file twice in a state table, but removing a file from the directory causes a read/write action failure after the removal.

Message: WO: YY, Error: File path name is larger than 255 [YY].

Meaning: Maximum length of the File path is 255 bytes.

Message: WO: YY, Error: Incorrect number[YY] of arguments.

Meaning: Check the syntax of the action.

Message: WO YY, Error: Invalid file open mode [Y] for file [YY].

Meaning: File open mode is not properly defined in the action string OPEN_MOD action. Check the syntax.

Message: WO YY, Error: Failed to open file YY [AA BB].

Meaning: Failed to open the file. Check the unix error message in the diagnostic message. AA represents the unix error message number and BB represents the unix error message.

Message: WO YY, Error: Failed to add the file [YY] in the active file list.

Meaning: Check the file pointer, file handler and file name, and the file name length. Also, check other messages in th: e diagnostic file.

Message: WO: YY, Error: Incorrect number [YY] of arguments for READ_FILE.

Meaning: Check the number of arguments in the action string.

Message: WO YY, Error: File handler [YY] conversion failed [AA BB].

Meaning: This points to conversion failure for the file handler. AA represents the unix error message number and BB represents the unix error message.

Message: WO YY, Error:Failed to get the read buffer name for [YY].

Meaning: Check the second argument of the action string for a proper syntax.

Message: WO YY, Error: File stat failed [AA BB].

Meaning: Failed to get file related information. AA represents the unix error message number and BB represents the unix error message.

Message: WO YY, Error: Failed to parse the second argument.

Meaning: Check the syntax of the second argument of the action string.

Message: Wrong file type.

Meaning: Contact Product Support.

Message: WO YY, Error: Error in the option argument [YY] [AA BB].

Meaning: Check the third argument of the READ_FILE action string for the proper syntax. AA represents the unix error message number and BB represents the unix error message. The syntax of the action function is important.

Message: WO YY, Error: Failed to locate the file with the file handler [ZZ].

Meaning: Check if the file is opened properly. If the problem persists, contact Product Support.

Message: WO YY, Error: Error in reading the file with the file handler [ZZ] [AA BB].

Meaning: This is a unix problem. AA represents the unix error message number and BB represents the unix error message.

Message: WO YY, Error: Failed to break the line to multiple lines.

Meaning: The read data cannot be broken and stored on a multiple variable. Check the data and syntax. Save the diagnostics and contact Product Support.

Message: WO YY: Error in reading the file pointed by the file handle YY [AA BB].

Meaning: Check the unix error message. AA represents the unix error message number and BB represents the unix error message.

Message: WO YY, Error: Invalid write argument [YY].

Meaning: Check the third argument of WRITE_FILE for valid options.

Message: WO YY: Error in writing to the file with the file handler [YY] [AA BB].

Meaning: Check the unix message. AA represents the unix error message number and BB represents the unix error message.

Message: WO YY: Error in getting the file handler value [YY].

Meaning : Check the action function syntax.

Message: WO YY: File handler [YY] can not be deleted.

Meaning: Check the logic of the state table to see if the file was previously opened. If the problem persists, contact Product Support.

Message: WO YY: Error in getting the file name from [YY].

Meaning: Check the action string of DEL_FILE.

Message: WO YY: File [YY] deletion failed.

Meaning: Check the existence of the file in the directory.

Message: WO YY: File [YY] can not be removed [AA BB].

Meaning: Check the unix message. AA represents the unix error message number and BB represents the unix error message.

Variables in State Table programs are created when you use them for the first time in a State Table. You do not have to define or declare them before they are used for the first time. If a variable is assigned a value, and does not already exist, it is created. If it does exist, it will be overwritten.

Variable names can consist of the following characters: a to z, A to Z, 0 to 9, “.", “[", “]" and “_", the underscore character.

The curly braces “{“ and "}" provide extended variable syntax and are used to inform the Interpreter to explicitly expand their contents first before expanding the rest of the action string. For example, consider the case in which an array index is itself a variable:

1000 CONCAT ‘%TMP=%{ARRAY[%IDX]}'

To ensure the correct expansion of this option string, it is essential that %IDX be expanded first before the %ARRAY. The % means that the value has been previously stored and will be substituted by the action function at run-time.

The use of curly braces is highly recommended when fully expanding variable names that include non-alphanumeric characters (especially dot “.", left bracket “[", or right bracket “]") carrying special meaning.

The term regular expression is used in the same context as the standard UNIX usage. A formal definition of regular expressions is available in the standard UNIX documentation under regexp. Most UNIX systems have this documentation on-line. It is available by typing the UNIX command:

man regexp

Expressions:

An expression is any legal combination of symbols that represents a value. An expression is defined as follows:

operator::= { ==, !=, <=, >=, <, >, NOT_NULL, IS_NULL, DEFINED, NOT_DEFINED}
expression ::= %var operator [{ %var | number | "string"}]

Data registers are a set of global registers in the Interpreter that are updated when the state table initiates an operation. The state table can access these registers by using a predefined set of variable names. Based on these and the contents of the registers, appropriate actions are taken in the state table. Only LAM actions can be used to update these registers. All other actions use the registers in a read-only manner.

The LAM registers are defined below.

The SNMP API provides the following actions to construct and submit requests:

The general syntax for invoking the above actions is:

Line  Action   '%Ret=Pid:Method:ArgList'

With this action you can invoke the SNMP GET request to retrieve the value of one or more variables from an SNMP agent.

Syntax:

SNMP_GET_REQ    '%PID=newPid'
SNMP_GET_REQ    '%RET=%PID:setOid:Oid1[…:OidN]'
SNMP_GET_REQ    '%RET=%PID:setAuthInfo:AuthInfo'
SNMP_GET_REQ    '%RET=%PID:setContextName:Name'
SNMP_GET_REQ    '%RET=%PID:setContextID:ContextID'
SNMP_GET_REQ    '%RET=%PID:send'      [Timeout]

See also "SNMP_RESPONSE," "SNMP_TABLE_REQ."

Example:

# Get a fresh PID
1000  SNMP_GET_REQ     '%PID=newPid'
# Get the sysDescr object
2000  SNMP_GET_REQ     '%RET=%PID:setOid:sysDescr.0'
# Submit the request
3000  SNMP_GET_REQ     '%RET=%PID:send'

This action provides methods to construct an SNMP Get Next request and submit it to the agent. You can invoke the SNMP_GET_NEXT_REQ to retrieve the next variable after one or more specified variables from an SNMP agent.

Syntax:

SNMP_GET_NEXT_REQ      '%PID=newPid'
SNMP_GET_NEXT_REQ      '%RET=%PID:setOid:Oid1[…:OidN]'
SNMP_GET_NEXT_REQ      '%RET=%PID:setAuthInfo:AuthInfo'
SNMP_GET_NEXT_REQ      '%RET=%PID:setContextName:Name'
SNMP_GET_NEXT_REQ      '%RET=%PID:setContextID:ContextID'
SNMP_GET_NEXT_REQ      '%RET=%PID:send' [Timeout]

See also "SNMP_RESPONSE," "SNMP_TABLE_REQ."

Example:

# Get a fresh PID
1000  SNMP_GET_NEXT_REQ      '%PID=newPid'
# Get the object next to sysUpTime object
2000  SNMP_GET_NEXT_REQ
   '%RET=%PID:setOid:sysUpTime.0'
# Submit the request
3000  SNMP_GET_NEXT_REQ      '%RET=%PID:send'

You can invoke SNMP_GET_BULK_REQ to retrieve large blocks of data efficiently from an SNMP agent.

See also "SNMP_RESPONSE," "SNMP_TABLE_REQ."

Syntax:

SNMP_GET_BULK_REQ      '%PID=newPid'
SNMP_GET_BULK_REQ      '%RET=%PID:setOid:Oid1[…:OidN]'
SNMP_GET_BULK_REQ      '%RET=%PID:setNonRepeaters:%Non-Repeaters'
SNMP_GET_BULK_REQ      '%RET=%PID:setMaxRepetitions:%Max-Repetitions'
SNMP_GET_BULK_REQ      '%RET=%PID:setAuthInfo:AuthInfo'
SNMP_GET_BULK_REQ      '%RET=%PID:setContextName:Name'
SNMP_GET_BULK_REQ      '%RET=%PID:setContextID:ContextID'
SNMP_GET_BULK_REQ      '%RET=%PID:send' [Timeout]

Example:

# Get a fresh PID
1000  SNMP_GET_BULK_REQ      '%PID=newPid'
# Set the Non-Repeaters parameter
2000  SNMP_GET_BULK_REQ      '%RET=%PID:setNonRepeaters:1'
# Set the Max-Repetitions parameter
3000  SNMP_GET_BULK_REQ 
  '%RET=%PID:setMaxRepetitions:2'
# Get entries in the IP net-to-media table
4000  SNMP_GET_BULK_REQ      '%RET=%PID:setOid:sysUpTime
   :ipNetToMediaPhysAddesss
   :ipNetToMediaType'
# Submit the request
5000  SNMP_GET_BULK_REQ      '%RET=%PID:send'

Invokes the SNMP SET request to set the value of one or more variables from an SNMP agent.

See also "SNMP_RESPONSE," "SNMP_TABLE_REQ."

Syntax:

SNMP_SET_REQ    '%PID=newPid'
SNMP_SET_REQ    '%RET=%PID:setOidVal:Oid:Val'
SNMP_SET_REQ    '%RET=%PID:setAuthInfo:AuthInfo'
SNMP_SET_REQ    '%RET=%PID:setContextName:Name'
SNMP_SET_REQ    '%RET=%PID:setContextID:ContextID'
SNMP_SET_REQ    '%RET=%PID:send' [Timeout]

Example:

100 SNMP_SET_REQ '%PID=newPid'
120 SNMP_SET_REQ '%RET=%PID:setOidVal:notifyConfirm.0:0x 07'
#120 SNMP_SET_REQ '%RET=%PID:setOidVal:notifyConfirm.0:0x 01 03'
#120 SNMP_SET_REQ '%RET=%PID:setOidVal:notifyConfirm.0:0x 0b 1f'
124 SNMP_SET_REQ '%RET=%PID:setAuthInfo:public'
200 SNMP_SET_REQ '%RET=%PID:send'