Examples of USS command conversion

This appendix contains examples of how to code USS tables to convert commands. Each example includes the following items:

The USS table used
The format for entering the command
The converted command

Example 1: Parameters omitted

The following VTAM® operator command is issued:

F NET,TNSTAT

All parameters are omitted and, therefore, defaults are used during conversion. The following operation-level USS table is used:

   USSTAB
   USSCMD CMD=TNSTAT,FORMAT=BAL
   USSPARM PARM=P1,REP=CNSL,DEFAULT=NO
   USSPARM PARM=P2,REP=TIME,DEFAULT=60
   USSEND

The converted command is

TNSTAT CNSL(NO) TIME(60)

Example 2: Positional and keyword parameters (FORMAT=PL1)

The terminal operator command

LOFF(PROG) T(COND)

is issued. Positional and keyword parameters are used with FORMAT=PL1. The following session-level USS table is used:

   USSTAB
   USSCMD CMD=LOFF,REP=LOGOFF,FORMAT=PL1
   USSPARM PARM=P1,REP=APPLID
   USSPARM PARM=T,REP=TYPE,DEFAULT=COND
   USSEND

The converted command is

LOGOFF APPLID(PROG) TYPE(COND)

Example 3: Positional and keyword parameters (FORMAT=PL1)

The terminal operator command

LOFF (PGM) T

is issued. A null value is taken instead of a default value. Positional and keyword parameters are used with FORMAT=PL1. The following session-level USS table is used:

   USSTAB
   USSCMD CMD=LOFF,REP=LOGOFF,FORMAT=PL1
   USSPARM PARM=P1,REP=APPLID
   USSPARM PARM=T,REP=TYPE,DEFAULT=COND
   USSEND

The converted command is

LOGOFF APPLID(PGM) TYPE( )

Because T was coded, the default value specified in the table is not used. If T had not been coded, TYPE(COND) would have resulted. TYPE( ) causes unconditional termination. Note that if you replace DEFAULT=COND with VALUE=COND in the table entry (USSPARM PARM=T,REP=TYPE,VALUE=COND), this command results in a TYPE(COND) instead of TYPE( ).

Example 4: Positional and keyword parameters (FORMAT=BAL)

The terminal operator command

LON PROGRAM,IN='7,3,JOhn'

is issued. Positional and keyword parameters are used with FORMAT=BAL.

The following session-level USS table is used:

   USSTAB
   USSCMD CMD=LON,REP=LOGON,FORMAT=BAL
   USSPARM PARM=P1,REP=APPLID,DEFAULT=TESTPROG
   USSPARM PARM=MODE,REP=LOGMODE,DEFAULT='PROMPT'
   USSPARM PARM=IN,REP=DATA
   USSEND

The converted command is

LOGON APPLID(PROGRAM) LOGMODE(PROMPT) DATA('7,3,JOhn')

Note that no character translation was performed on JOhn because there were single quotation marks around it. Note also that the single quotation marks around PROMPT in the default declaration have been deleted (by the assembler when the USS table was assembled).

Example 5: Using parameter not defined in USS table

The VTAM operator command

F NET,IMR,ID=PU12,OPT=ACT,RECLIM=200

is issued. A parameter (ID) is used that is not defined on the USS table.

The following operation-level USS table is used:

   USSTAB
   USSCMD CMD=IMR,FORMAT=BAL
   USSPARM PARM=OPT,DEFAULT=ACT
   USSPARM PARM=RECLIM,DEFAULT=10
   USSEND

The converted command is

IMR ID(PU12) OPT(ACT) RECLIM(200)

Because ID is not defined by a USSPARM macroinstruction in the USS table, the keyword is not changed during conversion.

Example 6: Renaming keyword replaced by verb

The VTAM operator command

F NET,XYZ,ID=PU12

is issued. This example shows how to rename a keyword that is replaced by a verb.

The following VTAM operator USS table is used:

   USSTAB
*
   USSCMD CMD=MODIFY,FORMAT=BAL
   USSPARM PARM=XYZ,REP=VERB,VALUE=XYZ
*
   USSCMD CMD=XYZ,REP=IMR,FORMAT=BAL
   USSPARM PARM=OPT,DEFAULT=ACT
   USSPARM PARM=RECLIM,DEFAULT=10
   USSEND

This results, after the first pass, in the following command of the form

VERB(XYZ) ID(PU12)

which in turn, after the second pass, results in the following converted command

IMR ID(PU12) OPT(ACT) RECLIM(10)

Note that the FORMAT=BAL specification on CMD=XYZ is ignored. After the first pass, VTAM uses the PL/I format for command processing.

Example 7: Using interpret and USS tables

If you want to use the facilities of both the USS table and the interpret table, the SEQNCE parameters in the interpret table should be coded to avoid a match during the first search of the interpret table (which would prevent the USS table from being used). Instead, a USSPARM statement in the USS table should be used to specify an APPLID that will match an interpret table entry during the second pass.

The interpret table is coded as follows:

XRFINTAB INTAB
         LOGCHAR  APPLID=(USERVAR,ZZIMSUV),SEQNCE='ZZIMS'
         ENDINTAB XRFINTAB

The USS table is coded as follows:

XRFUSTAB USSTAB
         USSCMD   CMD=IMS,REP=LOGON,FORMAT=PL1
         USSPARM  PARM=P1,REP=APPLID,DEFAULT=ZZIMS
         USSPARM  PARM=P2,REP=LOGMODE,DEFAULT=ILOGMODE
         USSEND
         END      XRFUSTAB

If the LOGON sequence entered by the terminal user is "IMS,"
- The interpret table will be searched for a matching entry, but none will be found.
- The message will be translated, using the information in the USS table, to read
```
LOGON APPLID(ZZIMS) LOGMODE(ILOGMODE)
```
- The interpret table will be searched again, this time using “ZZIMS,” the string specified as the APPLID in the reformatted LOGON message. Because “ZZIMS” does match an entry in the interpret table, the information in that entry will be used. If the current value of the USERVAR ZZIMSUV is “IMS1,” the session will be established to the IMS1 application.
On the other hand, if the LOGON sequence entered by the terminal user is “ZZIMS,” a match will be found during the initial search of the interpret table; Therefore, the USS table will not be used (the LOGMODE operand specified in the USS table will not be added). The USERVAR specified in the interpret table entry will still be used.

Example 8: Using TRANSLATE=NO to pass a mixed case password, assuming the translation table is used to convert all text to upper case.

The terminal operator command

app11 user1/PaSsWrD1 interact

is issued. Positional parameters are used with FORMAT=PL1. The following session-level USS table is used:

   AUSSTAB USSTAB
   APPL1   USSCMD CMD=APPL1,REP=LOGON,FORMAT=PL1
           USSPARM PARM=APPLID,REP=APPLID,DEFAULT=APPL1
           USSPARM PARM=P1,REP=DATA,TRANSLATE=NO
           USSPARM PARM=P2,REP=LOGMODE
           USSEND

The converted command is

LOGON APPLID(APPL1) DATA(user1/PaSsWrD1) LOGMODE(INTERACT)

Note: No character translation was performed on user1/PaSsWrD1 because TRANSLATE=NO was coded on the DATA USSPARM

Example 9: Using the default TRANSLATE=YES to pass a mixed case password, assuming the translation table is used to convert all text to upper case.

The terminal operator command

app11 'user1/PaSsWrD1'

is issued. Positional parameters are used with FORMAT=PL1. The following session-level USS table is used:

   AUSSTAB USSTAB
   APPL1   USSCMD CMD=APPL1,REP=LOGON,FORMAT=PL1
           USSPARM PARM=APPLID,REP=APPLID,DEFAULT=APPL1
           USSPARM PARM=P1,REP=DATA
           USSPARM PARM=P2,REP=LOGMODE
           USSEND

The converted command is

LOGON APPLID(APPL1) DATA('user1/PaSsWrD1') LOGMODE(INTERACT)

Note: No character translation was performed on user1/PaSsWrD1 because there were single quotation marks around it. The single quotation marks are removed before the data is passed to the application.

For further information on converting USS commands, see the z/OS Communications Server: SNA Network Implementation Guide.