UDSADM statements

The statement formats of the UDSADM administration program comply with SDF (System Dialog Facility) conventions; see the manuals "SDF Dialog Interface" and the commands manuals of "BS2000 OSD/BC". Uppercase letters printed in boldface denote guaranteed abbreviations of keywords.

Overview of UDSADM statements

Statement	Meaning
CONNECT-CONFIGURATION     CONFIGURATION-NAME = <name>    ,PASSWORD = *NONE / <x-string>                <c-string>    ,HOST = *LOCAL / <name>	Sets up connection to UDS/SQL configuration
DISCONNECT-CONFIGURATION	Clears connection to UDS/SQL configuration
END	Terminates UDSADM
EXECUTE-DAL-CMD     CMD = <dal-cmd>	Executes DAL commands
HELP-DAL-CMD     ?	Help function for DAL commands
MODIFY-MSG-FORMAT     HEADER = NO / YES	Sets message output format
MODIFY-MSG-WAIT-TIME     TIME = STD /             <integer 1..7200 seconds>	Sets wait time for DAL commands
SET-RECEIVE-MODE	Activates permanent receive task
SHOW-CONNECTION-ATTRIBUTES	Displays information on connection
SHOW-OUTSTANDING-MSG	Displays outstanding messages

Table 11: UDSADM statements

UDSADM statements entered incorrectly are rejected with a specific message and can be corrected. Each UDSADM statement entered correctly is executed immediately.

Statement selection rules

Statement	Selection rules
END HELP-DAL-CMD MODIFY-MSG-FORMAT MODIFY-MSG-WAIT-TIME	These statements may be entered at any time.
DISCONNECT-CONFIGURATION	This statement is permitted only for a connection that was previously set up using CONNECT-CONFIGURATION.
CONNECT-CONFIGURATION	This statement is permitted for a connection not yet set up.
EXECUTE-DAL-CMD SET-RECEIVE-MODE SHOW-CONNECTION-ATTRIBUTES SHOW-OUTSTANDING-MSG	These statements are permitted only between CONNECT-CONFIGURATION and DISCONNECT.

Table 12: Statement selection rules

Setting up a connection to the UDS/SQL configuration (CONNECT-CONFIGURATION)

This statement sets up a connection between UDSADM and a UDS configuration via DCAM.
If there is already a connection to the communication partner, this statement is rejected and a message output.

CONNECT-CONFIGURATION

CONFIGURATION-NAME = <name>

,PASSWORD = *NONE / <x-string> / <c-string>
,HOST = *LOCAL / <name>

CONFIGURATION-NAME = <name>
Name of the DCAM application to which UDSADM is to be connected. The name is formed from the first eight characters of the UDS/SQL configuration name.

Example

UDS/SQL configuration name            CONFIGURATION-NAME
UDSADMTESTDB                          UDSADMTE 
UDSADM                                UDSADM 
UDSA                                  UDSA

PASSWORD = *NONE
If no administration password has been defined for the UDS/SQL configuration, you do not have to specify anything for PASSWORD. 

PASSWORD = <x-string> / <c-string>
Administration password for administration via DCAM. This password may be up to four bytes long and has the following format:

X’nnnnnnnn’ 

one to eight hexadecimal digits

C’xxxx’    one to four alphanumeric characters

If an administration password has been defined for the UDS/SQL configuration, you must specify it here.

HOST = *LOCAL
Name of the local host. If the UDS/SQL configuration to be administered runs on the local host, you do not have to specify anything for HOST.

HOST = <name>
Name of the host on which the UDS/SQL configuration to be administered runs. This name may be up to eight characters long. 

Clearing a connection to the UDS/SQL configuration (DISCONNECT-CONFIGURATION)

This statement clears a connection between UDSADM and a UDS/SQL configuration.If there is no connection with a communication partner, this statement is rejected and a UDSADM message output.
If there is a connection with the communication partner, it is cleared and an acknowledgment is output.

DISCONNECT-CONFIGURATION                    

This statement has no operands. 

Terminating UDSADM (END)

This statement terminates UDSADM.
Any existing connection with the communication partner is cleared and an acknowledgment is output.

END                    

This statement has no operands.

Executing DAL commands (EXECUTE-DAL-CMD)

This statement sends the UDS/SQL or UDS-D DAL command specified for dal-cmd to the UDS/SQL configuration. UDSADM waits until UDS/SQL acknowledges receipt of the command and then issues a corresponding message.

In the case of DAL commands that require a response, UDSADM waits up to the maximum wait time set.

If the DAL response arrives within this time, it is received in its entirety and output. UDSADM then branches back to its basic state and can process further UDSADM input.

While UDSADM is waiting for the DAL response, all messages arriving from the UDS/SQL configuration are received and output.
If no DAL response arrives within the wait time, a UDSADM message is output. UDSADM branches back to its basic state and can process further UDSADM input.

The outstanding DAL response can then be received at a later time using one of the UDSADM receive functions.

EXECUTE-DAL-CMD                    

CMD = <dal-cmd>

CMD = <dal-cmd>

dal-cmd can be up to 64 characters long. UDSADM does not check the syntax of the DAL commands.

• If the wait time set is too short (< 5 seconds), the DCAM message buffer between the UDS/SQL configuration and UDSADM may not be large enough in the short term. Once the wait time has expired, UDSADM reports that there are no more messages. The UDSADM statement SET-RECEIVE-MODE can be used to receive the rest of the DAL result. If more than 30 seconds have passed, DAL messages may have been lost. In this case, you should repeat the DAL command with a longer wait time.

• If UDSADM is called in a procedure, you must ensure that the DAL commands for UDS-D cannot be mistaken for symbolic procedure names (see the commands manuals of "BS2000 OSD/BC", ESCAPE-CHARACTER parameter in the BEGIN-PROCEDURE command). You can do this by specifying the character "&" twice in the UDS-D DAL command.

• You should note that UDSADM interprets a final hyphen as a continuation character. This can lead to difficulties if entered DAL commands terminate with a hyphen that forms part of the DAL command (see "DAL syntax” ).

Help function for DAL commands (HELP-DAL-CMD)

You can use this statement to find out the meaning of individual DAL commands. The syntax of the DAL commands is described with examples.

When you enter this statement, a list of all the DAL commands is output. You can request the meaning of individual DAL commands by entering question marks.

You cannot execute DAL commands using this statement.

HELP-DAL-CMD                    

?

The question mark has to be specified. 

Setting the message output format (MODIFY-MSG-FORMAT)

This statement allows you to set the message output format. UDSADM outputs UDS/SQL messages, UDS-D messages and DAL responses to SYSOUT in the output format set here.

MODIFY-MSG-FORMAT                    

HEADER = NO / YES

HEADER = NO
The message is output to SYSOUT without a message header.

HEADER = YES
The message is output to SYSOUT with a message header; see the "Messages" manual, formatted message output.

Setting the wait time for receiving messages (MODIFY-MSG-WAIT-TIME)

This statement allows you to set the time, in seconds, that UDSADM is to wait for the arrival of a message (DAL response, UDS/SQL or UDS-D message).
If the message arrives within this wait time, it is received in its entirety and output.
If the message does not arrive within the wait time, UDSADM branches back to its basic state and can process further UDSADM input.
The outstanding message can then be received at a later time using one of the UDSADM receive functions.

MODIFY-MSG-WAIT-TIME                    

TIME = STD / <integer 1..7200 seconds>                    

TIME = STD

The wait time is set to the default value. The default value is 12 seconds in interactive mode or 60 seconds in batch mode.

TIME = <integer 1..7200 seconds >
The value of the wait time must be within the specified limits. Values of between 1 and 7200 seconds may be specified.

If the setting made for the TIME parameter is too low, messages may be lost (see "Note").

Activating a permanent receive task (SET-RECEIVE-MODE)

This statement activates a receive task in UDSADM. UDSADM is now in receive mode and receives and outputs all incoming messages (DAL responses, UDS/SQL and UDS-D messages).
When UDSADM is in this state, no input is accepted. The receive task can be interrupted with the [K2] key. UDSADM then branches back to its basic state and can process further UDSADM input.

SET-RECEIVE-MODE                    

This statement has no operands.

UDSADM should normally be set to receive mode so that no messages are lost. If no UDSADM receive function has been used for a long time, it may be that messages are being lost during transport via DCAM.

Displaying connection information
(SHOW-CONNECTION-ATTRIBUTES)

This statement is used to output information on the connection.

SHOW-CONNECTION-ATTRIBUTES                    

This statement has no operands.

The connection information has the following format:

UDSADM own-appl IN HOST own-name CONNECTED TO:

CONFNAME	HOSTNAME	SECLEVEL	CON-DATE	CON-TIME
confname	host	n	yyyy-mm-dd	hh:mm:ss

The connection information should be interpreted as follows:

own-appl
	DCAM application name of UDSADM in UAD@tsn format. UAD@ is a fixed string. tsn is the task sequence number of the UDSADM task.
own-name
	Name of the host on which UDSADM is running.
confname
	UDS/SQL configuration name; used as the DCAM application name.
host	BCAM name of the host on which the UDS/SQL configuration to be administered runs.
SECLEVEL
	Security level of the UDS/SQL configuration to be administered.  This column is now only output for reasons of compatibility. n = NO  normal security level
CON-DATE
	Date of connection setup to the UDS/SQL configuration.
CON-TIME
	Time of connection setup to the UDS/SQL configuration.

Displaying outstanding messages (SHOW-OUTSTANDING-MSG)

This statement is used to display outstanding messages (DAL responses, UDS/SQL and UDS-D messages).
If there are any outstanding messages when the statement is issued, they are output. Once all the messages have been output, UDSADM branches back to its basic state and can process further UDSADM input.
If there are no outstanding messages, a UDSADM message is issued. UDSADM branches back to its basic state and can process further UDSADM input.

SHOW-OUTSTANDING-MSG                    

This statement has no operands.