UPDATE OTMADESC command

Subsections:

• Environment
• Syntax
• Keywords
• Usage notes
• Output fields
• Return, reason, and completion codes
• Examples

Environment

The following table lists the environments (DB/DC, DBCTL, and DCCTL) in which you can use the commands and keywords.

Syntax

                               .-,-------------.     
                               V               |     
>>---UPDATE----OTMADESC--NAME(-----destname*---+-)-------------->

>--SET(-+-| A |-+-)--+---------------+-------------------------><
        +-| B |-+    |       .-N-.   |   
        '-| C |-'    '-EXIT(-+-Y-+-)-'   

A (Descriptor TYPE=IMSCON)

|--+----------------------------------------------+------------->
   '-ADAPTER(adaptername)--CONVRTR(convertername)-'   

>--+----------------------------------------------+------------->
   '-RMTIMSCON(rmtimsconnect)--RMTIMS(remote_IMS)-'   

>--+-------------------+--SMEM(-+-N-+-)--SYNTIMER(syntimer)----->
   '-RMTTRAN(trancode)-'        '-Y-'                         

>--TMEMBER(tmem)--TPIPE(tpipename)--+-----------------+---------|
                                    '-USERID(user_id)-'   

B (Descriptor TYPE=IMSTRAN)

|--+---------------+--+------------------+---------------------->
   '-TMEMBER(tmem)-'  '-TPIPE(tpipename)-'   

>--+---------------------+--+-------------------+--------------->
   '-LTERMOVR(ltermname)-'  |           .-Y-.   |   
                            '-REPLYCHK(-+-N-+-)-'   

>--+---------------+--+-------------------------+---------------|
   |       .-N-.   |  '-SYNTIMER(timeout value)-'   
   '-SMEM(-+-Y-+-)-'                                

C (Descriptor TYPE=MQSERIES)

|--TMEMBER(tmem)--+------------------+-------------------------->
                  '-TPIPE(tpipename)-'   

>--+--------------------------+--+----------------+------------->
   |           .-COPYMTOC-.   |  '-USERID(userid)-'   
   '-MQREPORT(-+-NEWMSGID-+-)-'                       
               +-PASSMSG1-+                           
               +-PASSCORR-+                           
               '-NONE-----'                           

>--+-------------------------+---------------------------------->
   |           .-MQIMSVS-.   |   
   '-MQFORMAT(-+-MQIMS---+-)-'   
               +-NONE----+       
               '-MQSTR---'       

>--+-------------------------------+--+---------------------+--->
   '-MQRTF(mqmd_replytoformatname)-'  '-MQMSGID(mqmd_msgid)-'   

>--+-------------------------+--MQRTQ(mqmd_replytoqueuename)---->
   '-MQCORREL(mqmd_correlid)-'                                 

>--+------------------------------------+----------------------->
   '-MQRTQMGR(mqmd_replytoqueuemgrname)-'   

>--+--------------------------------+--+-------------------+---->
   '-MQAPPLID(mqmd_appidentitydata)-'  |           .-Y-.   |   
                                       '-MQCOPYMD(-+-N-+-)-'   

>--+-----------------+--+------------------+--------------------|
   |         .-N-.   |  |          .-N-.   |   
   '-SYNCTP(-+-Y-+-)-'  '-MQPERST(-+-Y-+-)-'   

Keywords

The following keywords are valid for the UPDATE OTMADESC command:

NAME(destname*)

A required keyword whose value cannot be modified.

SET()

Specifies to update the descriptors with at least one of the following keywords. The update applies to each of the descriptor names specified in the NAME keyword. If an asterisk is appended to the descriptor name, the update will not be applied to the group of names it is trying to mask.

ADAPTER(adaptername)

An optional parameter for TYPE(IMSCON) that identifies the IMS Connect adapter. adaptername is a 1- to 8-character adapter name. To clear the value of this keyword, specify the keyword with no value, for example, ADAPTER(). If the ADAPTER keyword is deleted, the CONVRTR keyword is also deleted. ADAPTER and TYPE(NONOTMA) are mutually exclusive.

CONVRTR(convertername)

A required parameter only if the ADAPTER keyword is specified. convertername is a 1- to 8-character converter name used by the adapter. The value of this keyword will be automatically deleted if the value of the ADAPTER keyword is being deleted. Coding this keyword without the ADAPTER keyword or with TYPE(NONOTMA) is not valid.

EXIT(N|Y)

When TYPE=IMSTRAN, this is an optional parameter used to indicate whether the IMS user exit (DFSCMUX0) can override the descriptor routing information for late messages.

For other descriptor types, this is an optional parameter used to specify whether the OTMA routing exits (DFSYPRX0 and DFYDRU0) can override the descriptor switch destination from ALT IOPCB.

LTERMOVR(ltermname)

When TYPE=IMSTRAN, this is an optional parameter used to specify a logical terminal name that overrides the name specified in the application I/O PCB. If an override name is also specified in the AIBRSNM2 field of the AIB, that name is used instead of the name in the descriptor. If an override name is not specified in the descriptor or the AIB, the IMS application terminal symbolic (PSTSYMBO) is used as the default logical terminal name for the target transaction.

MQAPPLID(mqmd_appidentitydata)

When TYPE=MQSERIES, this is an optional parameter that specifies a 1- to 32-character value for the MQMD_APPLIDENTITYDATA field. This field is used to pass data to the receiving IBM MQ application. The default is 32 blanks.

MQCOPYMD(Y | N)

When TYPE=MQSERIES, this is an optional parameter that specifies whether the original input values of the MQMD data structure from the MQ IMS Bridge are copied to the output message.

MQCORREL(mqmd_correlid)

When TYPE=MQSERIES, this is an optional parameter that specifies a 1- to 24-character value for the MQMD_CORRELID field. This value is passed directly to the receiving IBM MQ application if the value of the MQREPORT parameter is PASSCORR. The default is 0.

MQFORMAT(MQIMSVS | MQIMS | NONE | MQSTR)

When TYPE=MQSERIES, this is an optional parameter that specifies value for the MQMD_FORMAT field. The default value is MQIMSVS.

MQMSGID(mqmd_msgid)

When TYPE=MQSERIES, this is an optional parameter that specifies a 1- to 24-character value for the MQMD_MSGID field. This value is passed directly to the receiving IBM MQ application if the value of the MQREPORT parameter is PASSMSG1.

MQPERST(N | Y)

When TYPE=MQSERIES, this is an optional parameter that specifies whether messages that use this descriptor are persistent on a SYNC TPIPE. Setting this parameter to Y is analogous to setting X’40’ for the output flag value of the DFSYDRU0 exit routine.

MQREPORT(COPYMTOC | NEWMSGID | PASSMSG1 | PASSCORR | NONE)

When TYPE=MQSERIES, this is an optional parameter that specifies the MQMD_REPORT field value for messages that use the descriptor. The default value is COPYMTOC. Each supported value corresponds to an equivalent value in the MQMD data structure:

Parameter value

Equivalent MQMD structure value

NEWMSGID

MQRO_NEW_MSG_ID

PASSMSGI

MQRO_PASS_MSG_ID

COPYMTOC

MQRO_COPY_MSG_ID_TO_CORREL_ID

PASSCORR

MQRO_PASS_CORREL_ID

PASSMSCO

MQRO_PASS_MSG_ID and MQRO_PASS_CORREL_ID

NONE

MQRO_NONE

MQRTF(mqmd_replytoformat)

When TYPE=MQSERIES, this is a 1- to 8-character value for the MQMD_REPLYTOFORMAT field. The default is 0.

MQRTQ(mqmd_replytoqueuename)

When TYPE=MQSERIES, this is a required parameter that specifies a 1- to 48-character value for the MQMD_REPLYTOQ field.

MQRTQMGR(mqmd_replytoqueuemanagername)

When TYPE=MQSERIES, this is an optional parameter that specifies a 1- to 48-character value for the MQMD_REPLYTOQMGR field. If this parameter is not specified, MQSeries® will use the local queue manager.

REPLYCHK(Y|N)

Specifies whether an IMS application replies to the IOPCB for a synchronous program switch request. When REPLYCHK=YES and the ICAL target application does not reply to the IOPCB or switch to another transaction, IMS gives the error return code X’0100’, with reason code X’0110’, and extended reason code X’0014’ instead of a timeout to the ICAL call. The default is Y.

RMTIMS

An optional 1- to 8-character name of a remote, destination IMS system for ALTPCB output messages. The RMTIMS value must match the value specified on the ID parameter of a DATASTORE statement in the configuration member of the remote IMS Connect instance specified on the RMTIMSCON parameter. This parameter is valid only when TYPE(IMSCON) is specified. To clear the value of this parameter, specify the parameter with no value, for example, RMTIMS(). Clearing the value of RMTIMS also clears the value of RMTIMSCON.

RMTIMSCON

An optional 1- to 8-character name of a connection to the remote IMS Connect instance that manages TCP/IP communications for the remote IMS system that is named on the RMTIMS parameter. This value must match the value specified on the ID parameter of the RMTIMSCON statement in the configuration file of the local IMS Connect instance that is managing TCP/IP communications for the IMS system in which the OTMA ALTPCB output messages are originating. This parameter is valid only when TYPE(IMSCON) is specified. To clear the value of this parameter, specify the parameter with no value, for example, RMTIMSCON(). Clearing the value of RMTIMSCON also clears the value of RMTIMS.

RMTTRAN

An optional 1- to 8-character name of the transaction name to use at the remote, destination IMS system named on the RMTIMS parameter. When this parameter is specified with RMTIMSCON and RMTIMS parameters, IMS OTMA sends the ALTPCB output messages to the remote IMS system for transaction processing. This parameter is valid only when TYPE(IMSCON) is specified. To clear the value of this parameter, specify the parameter with no value, for example, RMTTRAN().

SMEM(N | Y)

An optional parameter that can either be a Y or N value to indicate whether the TMEMBER name specified in the TMEMBER parameter is a super member. To clear the value of this keyword, specify the keyword with no value, for example, SMEM(). Deleting SMEM() will default to SMEM(N). If the TMEMBER name is a super member, the length of the TMEMBER name has a maximum of 4 characters. SMEM and TYPE(NONOTMA) are mutually exclusive.

SYNCTP(N | Y

When TYPE=MQSERIES, this parameter specifies whether a SYNC TPIPE must be created for messages that use this descriptor. Setting this parameter to Y is analogous to setting X’80’ for the output flag value of the DFSYDRU0 exit routine.

SYNTIMER(syntimer)

An optional parameter used for synchronous callout processing. In synchronous callout processing, a request is canceled if an ACK/NAK or response is not received by OTMA from the client within the time specified. This value is expressed in hundredths of a second or milliseconds. The value can be numeric with a maximum length of six digits. The value has a range of 0 through 999999 and when zero is specified, it will default to 10 seconds or 1000 hundredths of a second. If you specify SYNTIMER() or SYNTIMER( ), the timeout value will be reset as if no timeout value has been specified.

If TYPE(IMSTRAN) is specified, this parameter is the timeout value for synchronous program switch ICAL calls. If a timeout value is also specified in the AIB interface, IMS will compare the timeout values and use the lower value.

TMEMBER(tmem)

A required parameter for TYPE(IMSCON). If the TYPE of the descriptor is being changed from IMSCON to NONOTMA, the value of this keyword will be deleted. If the TYPE of the descriptor is being changed from NONOTMA to IMSCON, then the TMEMBER keyword must be coded. tmem is a 16-character OTMA TMEMBER name or a 4-character super member. TMEMBER and TYPE(NONOTMA) are mutually exclusive.

An optional parameter for TYPE(IMSTRAN). The tmem value is a 1- to 16-character OTMA TMEMBER name. IMS queues late responses from a synchronous program switch to this OTMA TMEMBER. The destination name is used as the default OTMA TPIPE name if the TPIPE parameter is not specified in the descriptor.

TPIPE(tpipename)

An optional parameter that is a 1- to 8-character TPIPE name when TYPE(IMSCON) is specified. To delete the value of this keyword, specify the keyword with no value, for example, TPIPE(). If this keyword is not specified, the TPIPE name is the destination name specified in the NAME keyword. TPIPE and TYPE(NONOTMA) are mutually exclusive.

An optional parameter for TYPE(IMSTRAN) that specifies a 1- to 8-character TPIPE name. This parameter defaults to the destination name. IMS queues late responses from a synchronous program switch to this OTMA TPIPE. A value for the TMEMBER parameter is required when TPIPE is specified.

USERID

For TYPE=IMSCON, this is an optional 1- to 8-character RACF® user ID. When this parameter is specified with RMTIMSCON, RMTTRAN, and RMTIMS parameters, a remote, destination IMS system uses the USERID value to perform transaction authorization. The value of USERID specified in the OTMA destination descriptor overrides the user ID provided by the IMS application program that issued the ISRT call to the OTMA ALTPCB. This parameter is valid only when TYPE(IMSCON) is specified.

For TYPE=MQSERIES, this is a 1- to 8-character user ID that corresponds with the MQMD_USERIDENTIFIER field in the MQMD data structure. This field allows the OTMA descriptor to override the default user ID in the MQMD structure. Specify the value *USERID* to use the IMS user ID value from the PST.

Usage notes

The UPDATE OTMADESC command is used to modify existing destination routing descriptors that were either included in DFSYDTx or added by using the CREATE OTMADESC command. A log record will be written to track changes and to persist from one IMS restart to another. The log record will also be used to track the currency of updates to an XRF alternate and to an RSR tracking environment. The checkpoint record is X4035 and the log record for the CREATE, UPDATE, and DELETE commands is X221B.

The UPDATE OTMADESC command cannot change the TYPE value for a destination descriptor. If you want to change the type for a descriptor, you must create a new descriptor with the CREATE OTMADESC command or by modifying the DFSYDTx member of the IMS.PROCLIB data set. You can then delete the existing descriptor.

Output fields

Return, reason, and completion codes

An IMS return and reason code is returned to OM by the UPDATE OTMADESC command. The OM return and reason codes that might be returned as a result of the UPDATE OTMADESC command are standard for all commands entered through the OM API.

The following table includes the return and reason codes and a brief explanation of the codes. The return or reason code returned for the command might also indicate an error from a CSL request.

The following table includes an explanation of the completion codes. Errors unique to the processing of this command are returned as completion codes. A completion code is returned for each action against an individual resource.

Table 4. Completion codes for the UPDATE OTMADESC command

Completion code	Completion code text	Meaning
0	Command completed successfully	The UPDATE OTMADESC command completed successfully for the resource.
151	Descriptor not found	The descriptor name does not exist.
153	Adapter blank, Convrtr not blank	The value of the ADAPTER keyword is blank and the value of the CONVRTR keyword is not blank. Either both keywords must be blank or both keywords must contain a valid name.
154	Adapter not blank, Convtr blank	The value of the ADAPTER keyword is not blank and the value of the CONVRTR keyword is not blank. Either both keywords must be blank or both keywords must contain a valid name.
156	SMEM=Y, super mbr name GT 4 char	The super member name in the TMEMBER keyword must have a maximum length of 4 characters.
159	TMEMBER is required for IMSCON	The type is being changed from NONOTMA to IMSCON, but the value of TMEMBER is blank.
162	Descriptor not available for upd	During update processing, the descriptor was deleted by another user.
167	SYNTIMER must have numeric value	The timeout value must have a value expressed in numbers within parenthesis.
169	SYNTIMER has nonnumeric value	The value must not contain alphabetic characters or any character that is not numeric.