UPDATE TRANDESC command

Updating a descriptor changes only those attributes explicitly specified on the UPDATE command. Attributes not specified retain their existing values. Any transaction resource or descriptor can be created using this descriptor as a model, by specifying the CREATE LIKE(DESC(descriptor_name)) command. Any descriptor or resource that was already created using this descriptor is not updated.

Subsections:

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

Environment

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

Syntax

                               .-,----.     
                               V      |     
>>-+-UPDATE-+--TRANDESC--NAME(---name-+-)----------------------->
   '-UPD----'                               

          .-,---------.                           
          V           |                           
>----SET(---+-| A |-+-+-)----+----------------+----------------><
            '-| B |-'        '-OPTION(ALLRSP)-'   

A

|--+-AOCMD(-+-CMD--+-)---------------+--------------------------|
   |        +-N----+                 |   
   |        +-TRAN-+                 |   
   |        '-Y----'                 |   
   +-CLASS(class)--------------------+   
   +-CMTMODE(-+-MULT-+-)-------------+   
   |          '-SNGL-'               |   
   +-CONV(-+-N-+-)-------------------+   
   |       '-Y-'                     |   
   +-DCLWA(-+-N-+-)------------------+   
   |        '-Y-'                    |   
   +-DEFAULT(Y)----------------------+   
   +-DIRROUTE(-+-N-+-)---------------+   
   |           '-Y-'                 |   
   +-EDITRTN(name)-------------------+   
   +-EDITUC(-+-N-+-)-----------------+   
   |         '-Y-'                   |   
   +-EMHBSZ(size)--------------------+   
   +-EXPRTIME(seconds)---------------+   
   +-FP(-+-E-+-)---------------------+   
   |     +-N-+                       |   
   |     '-P-'                       |   
   +-INQ(-+-N-+-)--------------------+   
   |      '-Y-'                      |   
   +-LCT(value)----------------------+   
   +-LPRI(value)---------------------+   
   +-MAXRGN(number)------------------+   
   +-MSGTYPE(-+-MULTSEG-+-)----------+   
   |          '-SNGLSEG-'            |   
   +-MSNAME(name)--------------------+   
   +-NPRI(value)---------------------+   
   +-PARLIM(value)-------------------+   
   +-PGM(name)-----------------------+   
   +-PLCT(value)---------------------+   
   +-PLCTTIME(hundredths of seconds)-+   
   '-RECOVER(-+-N-+-)----------------'   
              '-Y-'                      

B

|--+-REMOTE(-+-N-+-)---+----------------------------------------|
   |         '-Y-'     |   
   +-RESP(-+-N-+-)-----+   
   |       '-Y-'       |   
   +-SEGNO(number)-----+   
   +-SEGSZ(size)-------+   
   +-SERIAL(-+-N-+-)---+   
   |         '-Y-'     |   
   +-SIDL(localsysid)--+   
   +-SIDR(remotesysid)-+   
   +-SPASZ(size)-------+   
   +-SPATRUNC(-+-R-+-)-+   
   |           '-S-'   |   
   +-TRANSTAT(-+-N-+-)-+   
   |           '-Y-'   |   
   '-WFI(-+-N-+-)------'   
          '-Y-'            

Keywords

The following keywords are valid for the UPDATE TRANDESC command:

NAME

Specifies the 1-8 character name of the transaction descriptor. Wildcards can be specified in the name. The name is a repeatable parameter. If the NAME parameter specified is a specific or wildcard name, command responses are returned for all the descriptor names that are processed. For NAME(*), command responses are returned only for the descriptor names that resulted in an error. OPTION(ALLRSP) can be specified with NAME(*) to obtain the command responses for all the descriptor names that are processed.

OPTION

Specifies additional functions to be performed along with the command.

ALLRSP

Indicates that the response lines are to be returned for all descriptors that are processed on the command. The default action is to return response lines only for the descriptors that resulted in an error. It is only valid with NAME(*). ALLRSP is ignored for other NAME values.

SET

Specifies the attribute values to be changed. A transaction must have the same characteristics in all systems where it is defined when it is shared. These characteristics include:

• Nonconversational or conversational
• SPA size if conversational
• Single-segment or multi-segment messages
• Non-inquiry or inquiry
• Recoverable or nonrecoverable

AOCMD

Specifies that the AOI option indicating whether the transaction can issue the type-1 AOI CMD call or the type-2 AOI ICMD call. If AOCMD is defined as CMD, TRAN, or Y, and the AOI1 execute parameter is defined as AOI1=N, no authorization checking is done, and the transaction is permitted to issue CMD and ICMD calls.

CMD

Indicates that the transaction is permitted to issue type-1 AOI CMD calls and type-2 AOI ICMD calls. If the AOI1 execute parameter is defined as C, R, or A, authorization checking is based on which transactions can issue a particular command. In this case, the commands (or first three characters of the commands) need to be defined to RACF® or equivalent product as a user. The type-1 AOI transactions must be defined as profiles under the TIMS class, and for each transaction, the commands it can issue must be specified. Defining AOCMD(CMD) requires you to create fewer user IDs than you need to create for the AOCMD(TRAN) definition. However, defining AOCMD(CMD) requires you to create or modify a larger number of resource profiles.

N

Indicates that the transaction is not permitted to issue AOI type-1 CMD calls. The transaction is permitted to issue AOI type-2 ICMD calls.

TRAN

Indicates that the transaction is permitted to issue type-1 AOI CMD calls and type-2 AOI ICMD calls. If the AOI1 execute parameter is defined as C, R, or A, the transaction code is used for authorization. The first authorization check results in the accessor environment element (ACEE) being built. This environment is kept for use by future authorization checks. The type-1 AOI transaction needs to be defined to RACF or equivalent product as a user. The transactions will then be specified on RACF PERMIT statements for each command they are allowed to issue from a type-1 AOI transaction. Specifying AOI transactions as users to RACF might conflict with the name of a user already defined to RACF. If this occurs, then either the transaction name or the existing user name needs to be changed.

Y

Indicates that the transaction is permitted to issue type-1 AOI CMD calls and type-2 AOI ICMD calls. If the AOI1 execute parameter is defined as C, R, or A, the user ID or program name is used for authorization. For some environments, if a Get Unique call has not yet happened, then the program name is used for authorization.

CLASS

Specifies the transaction class, which is an attribute used to select a transaction for scheduling. A transaction can be scheduled if there is a message processing region available for that class. The value can be a number from 1 to 999. This value must not exceed the value given (by specification or default) on the MAXCLAS= keyword of the IMSCTRL macro.

Define CPI-C transactions with a different message class from that used for non-CPI-C transactions. IMS™ handles all CPI-C transactions as priority zero within the transaction class.

CMTMODE

Specifies when database updates and non-express output messages are committed. This operand affects emergency restart.

MULT

Database updates and non-express output messages are committed only when the application program terminates normally, when the processing limit count has been reached, or, in the case of a pseudo-WFI dependent region, when there are no more messages on the queue. For example, if five transactions are processed during a single schedule of a program, all five are committed only when the fifth one is completed and the program terminates. Until a transaction has been committed, locks for updated database records are not released and non-express output messages are not queued for output. If an application ends abnormally before committing its messages, emergency restart requeues all the messages that were processed within the commit scope and makes them available for reprocessing.

If the transaction results in the application calling an external subsystem, such as DB2®, the Commit Verify exit provided by the external subsystem can determine whether CMTMODE(MULT) is supported. See documentation under the Commit Verify exit routine.

SNGL

Database updates and non-express output messages are committed when the application program completes processing each transaction. IMS invokes commit processing either when the application program requests the next message (issues a GU to the IO-PCB), or when the application program terminates. If an application ends abnormally before committing its messages, emergency restart requeues all the messages that were processed within the commit scope and makes them available for reprocessing. If an application ends abnormally before committing its message, emergency restart requeues the message that was in process before the abend and makes it available for reprocessing.

Keyword combination rules include the following:

• CONV(Y) and CMTMODE(MULT) are mutually exclusive.
• WFI(Y) and CMTMODE(MULT) are mutually exclusive.

CONV

Specifies the conversation option.

N

The transaction is not conversational.

Y

The transaction is conversational. The transaction message is destined for a conversational program. A conversational program processes transactions made up of several steps. A conversational program receives a message from a terminal, replies to the terminal, but saves the data from the transaction in a scratchpad area (SPA). When the person at the terminal enters more data, the program has the data it saved from the last message in the SPA, so it can continue processing the request without the person at the terminal having to enter the data again.

Keyword combination rules include the following:

• CONV(Y) requires SPASZ and SPATRUNC.
• CMTMODE(MULT) and CONV(Y) are mutually exclusive.
• INQ(Y) and CONV(Y) are mutually exclusive.
• RECOVER(N) and CONV(Y) are mutually exclusive.
• SPASZ and CONV(N) are mutually exclusive.
• SPATRUNC and CONV(N) are mutually exclusive.

DCLWA

Specifies the log write-ahead option.

N

If N is specified, IMS does not perform log write-ahead. Specify N if input message integrity and the consistency of output messages with associated database updates is not required. DCLWA does not apply to response mode or Fast Path input processing, and is ignored during IMS execution.

Y

If Y is specified, IMS performs log write-ahead for recoverable, nonresponse input messages and transaction output messages. This ensures the following:

• A nonresponse input transaction is made recoverable across IMS failures, before IMS acknowledges receipt of the input.
• Database changes are made recoverable before IMS sends associated output reply messages.
• Information in the log buffers is written to the IMS log, before the associated input acknowledgment or output reply is sent to the terminal.

Define DCLWA(Y) for all VTAM® terminal types.

DEFAULT(Y)

Specifies this descriptor as the default, which resets the existing default descriptor to DEFAULT(N). When a descriptor is created without the LIKE keyword, any attribute not specified on the CREATE command takes the value defined in the default descriptor. Only one descriptor can be defined as the default for a resource type. IMS defines transaction descriptor called DFSDSTR1, where all attributes are defined with the default value. Defining a user-defined descriptor to be the default overrides the current default descriptor. Since only one transaction descriptor can be the default at one time, only one transaction descriptor name can be specified with DEFAULT(Y).

DIRROUTE

Specifies the MSC directed routing option.

N

The application program processing a transaction is not informed of the system which originated the transaction. The name of the originating LTERM is placed in the I/O PCB.

Y

The application program processing a transaction is informed of the system which originated the transaction, if MSC directed routing is used in a multiple IMS system configuration. An MSNAME corresponding to a logical path back to the originating system is placed in the I/O PCB.

EDITRTN

Specifies the 1- to 8-character name of your transaction input edit routine that edits messages before the program receives the message. This name must be alphanumeric (A through Z, 0 through 9, #, $, and @). It must begin with an alphabetic character (A through Z, #, $, @). It cannot include a blank, comma, period, hyphen, or equal. It cannot include wildcard characters * or %.

The specified edit routine can either be an edit routine defined during the system definition process with the EDIT= parameter on the TRANSACT macro or it can be a new routine. If the routine is a new routine, the routine must reside in one of the RESLIB concatenated data sets. A maximum of 255 input edit routines are supported.

If the edit routine specified on the command is new to IMS, IMS attempts to load the routine from RESLIB. If the load fails, the command is rejected. If the edit routine specified is already defined to IMS, a decision is made whether to load a new copy of the routine or to use the existing copy. If the routine was generated into the system, but there are no transactions referencing the routine, IMS first attempts to load a new copy of the module from RESLIB. If the load is successful, the dynamic copy of the edit routine is used. The generated copy cannot be used again unless IMS is cold started. If the load of the dynamic routine fails, the generated copy is used. If the edit routine was generated into the system and other transactions reference it, the generated copy of the module is used.

EDITRTN is used for a Fast Path potential transaction when the transaction is routed to IMS.

For input from LU 6.2 devices, the user edit exit routine DFSLUEE0 is called instead of the transaction input edit routine specified in EDITRTN.

FP(E) and EDITRTN are mutually exclusive.

A zero value can be specified for the EDITRTN() parm (EDITRTN(0)) to remove an edit routine name from a transaction definition.

EDITUC

Specifies the edit to uppercase option.

N

The input data is not translated to uppercase. It can consist of uppercase and lowercase characters as entered from the terminal.

Y

The input data is to be translated to uppercase before it is presented to the processing program. If FP(E) or FP(P), the transaction is to be translated to uppercase before being presented to the edit/routing exit routine.

Specifying EDITUC(Y) for VTAM terminals prevents the transmission of embedded device control characters.

EMHBSZ

Specifies the EMH buffer size required to run the Fast Path transaction. This overrides the EMHL execution parameter. If EMHBSZ is not specified, the EMHL execution parameter value is used. The value can be a number from 12 to 30720.

Keyword combination rules include the following:

• EMHBSZ > 0 requires Fast Path to be defined.
• FP(N) and EMHBSZ>0 are mutually exclusive.

EXPRTIME

Specifies the elapsed time in seconds that IMS can use to cancel the input transaction. After a transaction is submitted to IMS, the transaction could be delayed for processing because of a stopped transaction or a potential system slow down. In that case, the user or client application could time out before the transaction is processed. When IMS eventually schedules and processes the transaction, the response message is no longer wanted. With the elapsed time specified for the transaction, IMS can flag the input transaction as expired so that the system does not waste CPU cycles to process the unwanted transaction.

The value can be a number, in seconds, which can range from 0 to 65535. The default is 0, which means that no expiration time is set for this transaction. The transaction expiration attribute is supported by all of the IMS TM interfaces.

Restriction: The transaction expiration checking is not performed at the GU time for Fast Path transactions, IMS conversational transactions, and program-to-program switch transactions.

FP

Specifies the Fast Path option.

E

The transaction is processed exclusively as Fast Path. The program must be defined as Fast Path exclusive.

N

The transaction is not a candidate for Fast Path processing. The program must be defined as not Fast Path. When FP(N) is specified, any attempt to use Fast Path resources or commands might yield unpredictable results.

P

The transaction is a potential candidate for Fast Path processing. Fast Path-potential transactions must be able to run under two applications: a Fast Path exclusive application and a non-Fast Path application. A Fast Path exclusive application should be defined to which this transaction can be routed. Fast Path–potential transactions must be processed by a user edit/routing exit to determine whether the transaction is actually to be processed by IMS Fast Path. If it is to be processed by IMS Fast Path, the edit/routing exit routine associates the transaction with a routing code. This routing code identifies which Fast Path application program is to process the transaction.

The program defined by PGM() must not be defined as Fast Path exclusive.

In order to update a transaction from FP(E) to FP(N) or from FP(N) to FP(E) you must also update the transaction to point to a program that has the same FP() attribute. If you do not update the program attribute, the command fails because of a program conflict.

Keyword combination rules include the following:

• EDITRTN and FP(E) are mutually exclusive.
• EMHBSZ>0 and FP(N) are mutually exclusive.
• FP(E) and FP(P) require Fast Path to be defined.
• MSGTYPE(MULTSEG) and FP(E) are mutually exclusive.
• MSGTYPE(MULTSEG) and FP(P) are mutually exclusive.
• MSNAME and FP(E) are mutually exclusive.
• RECOVER(N) and FP(E) are mutually exclusive.
• RECOVER(N) and FP(P) are mutually exclusive.
• RESP(N) and FP(E) are mutually exclusive.
• RESP(N) and FP(P) are mutually exclusive.
• SIDL and FP(E) are mutually exclusive.
• SIDR and FP(E) are mutually exclusive.

INQ

Specifies the inquiry option.

N

This is not an inquiry transaction.

Y

This is an inquiry transaction. If INQ(Y) is specified, you can also specify whether this transaction should be recovered during an IMS emergency or normal restart using the RECOVER() parameter.

This option should be specified only for those transactions that, when entered, do not cause a change in any database. Programs are prohibited from issuing ISRT, DLET, or REPL calls to a database when scheduled to process a transaction defined as INQ(Y).

An application program cannot do an SQL INSERT, DELETE, or UPDATE when the IMS transaction is defined with INQ(Y).

Keyword combination rules include the following:

• CONV(Y) and INQ(Y) are mutually exclusive.
• RECOVER(N) and INQ(N) are mutually exclusive.

LCT

Specifies the limit count. This is the number that, when compared to the number of input transactions queued and waiting to be processed, determines whether the normal or limit priority value is assigned to this transaction. The value can be a number from 1 to 65 535. The default is 65 535.

The limit count value is ignored for a transaction processed by a BMP.

The limit count value is ignored in a shared queues environment.

LPRI

Specifies the limit priority. This is the scheduling priority to which this transaction is raised when the number of input transactions enqueued and waiting to be processed is equal to or greater than the limit count value. The scheduling priority is an attribute used to select a transaction for scheduling. A transaction of higher priority is scheduled before a lower priority one, if they are defined with the same class. The value can be a number from 0 through 14.

When the limit priority is used and the scheduling priority is raised to the limit priority, the priority is not reduced to the normal priority until all messages enqueued for this transaction name are processed. If you do not want the limit priority for this transaction, define equal values for the normal priority and limit priority, and a limit count of 65535.

When a transaction is processed exclusively by a batch message program (BMP), define the limit priority as 0. If the program specified by PGM() is defined with a program type of batch, the current priority is forced to be 0. However, a batch message processing region (BMP) can process transactions with current scheduling priorities other than 0.

This priority also controls the priority of messages created by this transaction and sent to a destination in a remote system. See also the discussion on MSC priorities under the NPRI definition.

The limit priority value is ignored for a transaction processed by a BMP.

The limit priority value is ignored in a shared-queues environment.

MAXRGN

Specifies the maximum region count. This limits the number of message processing program (MPP) regions that can be concurrently scheduled to process a transaction. When the number of MPP regions is not limited, one transaction might monopolize all available regions. The value can be a number from 0 to the value specified on the MAXPST= control region parameter. MAXRGN(0) means that no limit is imposed.

If you define the application program with a scheduling type of SERIAL, omit the MAXRGN keyword or define it as 0.

The following keyword combinations are mutually exclusive:

• PARLIM(65535) and MAXRGN value greater than 0
• SERIAL(Y) and MAXRGN value greater than 0

MSGTYPE

Specifies the message type (single segment or multiple segment). It specifies the time at which an incoming message is considered complete and available to be routed to an application program for subsequent processing.

If MSC-directed routing is used in a multiple IMS system configuration, IMS does not ensure that both the message and the transaction destined to process that message are either single segment or multiple segments.

MULTSEG

The incoming message can be more than one segment in length. It is not eligible for scheduling to an application program until an end-of-message indication is received, or a complete message is created by MFS.

SNGLSEG

The incoming message is one segment in length. It becomes eligible for scheduling when the terminal operator indicates end-of-segment.

Keyword combination rules include the following:

• FP(E) and MSGTYPE(MULTSEG) are mutually exclusive.
• FP(P) and MSGTYPE(MULTSEG) are mutually exclusive.
• RESP(Y) and MSGTYPE(MULTSEG) are mutually exclusive.

MSNAME

Specifies the one- to eight-character name of the logical link path in a multiple IMS system configuration (MSC). A logical link path is a path between any two IMS systems. The IMS systems are identified by the remote system ID and the local system ID associated with the logical link path. The remote system ID identifies the system in which messages using this path are to be processed. The local system ID identifies this system. For an UPDATE TRAN command that is changing a transaction to a remote transaction, or changing the MSC path, the new MSNAME must already be defined.

Keyword combination rules include the following:

• FP(E) and MSNAME are mutually exclusive.
• SIDL and MSNAME are mutually exclusive.
• SIDR and MSNAME are mutually exclusive.

NPRI

Specifies the normal scheduling priority. The scheduling priority is an attribute used to select a transaction for scheduling. A transaction of higher priority is scheduled before a lower priority one, if they are defined with the same class. The normal priority is assigned to the transaction as the scheduling priority when the number of input transactions enqueued and waiting to be processed is less than the limit count value. The value can be a number from 0 through 14. The default is 1.

This priority also controls the priority of messages created by this transaction and sent to a destination in a remote system.

When a transaction is processed exclusively by a batch message program (BMP), code the normal priority as 0.

When a transaction is processed exclusively by a batch message program (BMP), define the limit priority as 0. If the application program specified by PGM() is defined with a program type of batch, the current priority is forced to be 0. However, a batch message processing region (BMP) can process transactions with current scheduling priorities other than 0.

For remote transactions, the priority used to send the transaction to the processing system, which is termed the MSC link message priority. The three MSC link message priority groups are:

• Low
• Medium
• High

The low priority group consists of primary requests in the input terminal system. This group is assigned remote transaction priorities from 0 to 6. The medium group consists of secondary requests, responses, primary requests in an intermediate system, and primary requests in the input terminal system. This group is assigned a remote transaction priority of 7. The high group consists of primary requests in the input terminal system. Messages in this group are assigned remote transaction priorities from 8 to 14. Within each group, messages have a priority based on the current priority value of the transaction or remote transaction in the input terminal system for primary requests, and on the latest processing system for secondary requests and responses.

In an MSC configuration, the transaction priority determines the priority used to send messages inserted by this transaction across an MSC link. If the transaction inserts multiple messages to the same destination (for example, pages to a printer) and these messages must be sent in the order inserted, the normal and limit priority values should be the same. If the normal and limit priority values are not identical, messages inserted at a higher priority than previously inserted messages could arrive at their destination first. (This restriction does not apply to multiple segments of the same message.)

The normal priority value is ignored for a transaction processed by a BMP.

PARLIM

Specifies the parallel processing limit count. This is the maximum number of messages that can currently be queued, but not yet processed, by each active message region currently scheduled for this transaction. This is the threshold value to be used when the associated application is defined with a scheduling type of parallel. An additional region is scheduled whenever the current transaction enqueue count exceeds the PARLIM value multiplied by the number of regions currently scheduled for this transaction.

The value can be a number from 0 to 32767 or 65535. PARLIM(0) indicates that any input message can cause a new region to be scheduled because the scheduling condition is always met (the number of messages is greater than zero). If you specify PARLIM(0), you should specify a MAXRGN value to limit the number of regions that can be scheduled to process a particular transaction. PARLIM(65535) means that parallel processing is disabled and IMS allows the transaction to be scheduled in only one region at a time.

The value specified for PARLIM applies to message processing programs (MPPs) only; it is not supported for batch message processing programs (BMPs).

If you define the application as SERIAL or the scheduling type as SERIAL, define PARLIM(65535).

In a shared-queues environment (when the scheduling type is PARALLEL), any PARLIM value other than 65535 causes a new region to be scheduled whenever the successful consecutive GU count exceeds the PARLIM value multiplied by the number of regions currently scheduled for this transaction. For shared queues environments, the successful consecutive GU count is used instead of the queue count. New regions continue to be scheduled up to the maximum number of regions specified on MAXRGN.

Keyword combination rules include the following:

• MAXRGN>0 and PARLIM(65535) are mutually exclusive.
• SERIAL(Y) and PARLIM value 0 - 32767 are mutually exclusive.

PGM

Specifies the name of the application program associated with the transaction. The program must exist unless the transaction is defined as REMOTE(Y).

PLCT

Specifies the processing limit count. This is maximum number of messages sent to the application program by the IMS for processing without reloading the application program. The value must be a number from 0 through 65535. PLCT(0) means the maximum number of messages sent to the application is one and the application program is reloaded before receiving a subsequent message. PLCT(65535) means that no limit is to be placed upon the number of messages processed at a single program load. Values 1 through 65535 are eligible for quick reschedule processing.

The value is used to determine how many messages an application program is allowed to process in a single scheduling cycle. When the application program requests, and receives, the number of messages indicated, any subsequent requests result in one of two things.

1. IMS indicates “no more messages exist” if any of the following conditions is true
   • The region is not an MPP.
   • The currently scheduled mode is not CMTMODE(SNGL).
   • Equal or higher priority transactions are enqueued for the region.

   IMS might, in fact, have other messages enqueued for the application program. It is the responsibility of the application program to terminate when it receives an indicator that no more messages are available. Termination of the application program makes the region it occupied available for rescheduling. This feature makes it possible for IMS to enable scheduling of higher priority transactions that entered the system while the previous transactions were in process. In addition, if any equal-priority transactions are enqueued, they become eligible for scheduling on a first-in, first-out (FIFO) basis.

2. The region goes through quick reschedule and returns the next message to the application of all of the following conditions are true.
   • The region is an MPP.
   • The transaction is CMTMODE(SNGL).
   • No equal or higher transactions are enqueued.
   • Messages are still enqueued for the application.

PLCTTIME

Specifies the processing limit count time. This is the amount of time (in hundredths of seconds) allowable to process a single transaction (or message). The number specifies the maximum CPU time allowed for each message to be processed in the message processing region.

Batch Message Programs (BMPs) are not affected by this setting.

The value can be a number, in hundredths of seconds, that can range from 1 to 6553500. A value of 6553500 means no time limit is placed on the application program.

If Fast Path is used this specifies, for a given transaction name, the amount of time (in hundredths of seconds) the program is allowed to process a single transaction message. The time represents real time that elapses during transaction processing (not accumulated task time). Real time is used because the input terminal is in response mode and cannot enter another transaction until the response is sent. In this case PLCT() is ignored.

The value controls application program looping. You are not required to optimize the value for program-transaction execution time. However, the time value assigned should not be less than the expected per-transaction execution time. If the scheduled application program exceeds the product of PLCTTIME() and PLCT(), the application program ends abnormally. If an IMS STIMER value of 2 is specified on the DFSMPR procedure, the region does not end abnormally until completion of the DL/I call.

The application program must not use STIMER timer services. IMS uses STIMER timer services to time the execution of transactions. If an application program issues an MVS™ STIMER macro, it cancels the STIMER timer services set by IMS. Use the STIMERM macro instead for application program timer requests.

RECOVER

Specifies the recovery option.

N

The transaction should not be recovered.

Y

The transaction should be recovered during an IMS emergency or normal restart.

Keyword combination rules include the following:

• CONV(Y) and RECOVER(N) are mutually exclusive.
• FP(E) and RECOVER(N) are mutually exclusive.
• FP(P) and RECOVER(N) are mutually exclusive.
• INQ(N) and RECOVER(N) are mutually exclusive.

REMOTE

Specifies the remote option.

N

The transaction is not remote. The transaction is local and runs on the local system.

Y

The transaction is remote. The transaction runs on a remote system.

REMOTE(Y) requires MSNAME or SIDR and SIDL.

RESP

Specifies the response mode option.

N

The transaction is not response mode. For terminals specifying or accepting a default of OPTIONS=TRANRESP, input should not stop after this transaction is entered.

Y

The transaction is response mode. The terminal from which the transaction is entered is held and prevents further input until a response is received. For terminals specifying or accepting a default of OPTIONS=TRANRESP, no additional messages are to be allowed after this transaction is entered until this transaction sends a response message back to the terminal. Response mode can be forced or negated by individual terminal definition. RESP(Y) is ignored during online processing for all terminals that do not operate in response mode.

Keyword combination rules include the following:

• FP(E) and RESP(N) are mutually exclusive.
• FP(P) and RESP(N) are mutually exclusive.
• MSGTYPE(MULTSEG) and RESP(Y) are mutually exclusive

SEGNO

Specifies the segment number. This is the maximum number of application program output segments that are allowed into the message queues per Get Unique (GU) call from the application program. The value can be a number from 0 through 65535. If SEGNO(0) is defined, the number of segments is not checked by the online system at execution time.

SEGSZ

Specifies the segment size. This is the maximum number of bytes allowed in any one output segment. The value can be a number from 0 through 65535. If SEGSZ(0) is defined, the segment size is not checked by the online system at execution time.

The maximum output message segment to an LU 6.2 device is 32767. If a transaction is expected to send output to an LU 6.2 device, the SEGSIZE parameter should be no greater than 32767. However, this is not enforced during processing of the command, because IMS cannot determine the device type for the message destination until output time.

SERIAL

Specifies the serial option.

N

Messages for the transaction are not processed serially. Message processing can be processed in parallel. Messages are placed on the suspend queue after a U3303 pseudoabend. Scheduling continues until repeated failures result in the transaction being stopped with a USTOP.

Y

Messages for the transaction are processed serially. U3303 pseudoabends do not cause the message to be placed on the suspend queue but rather on the front of the transaction message queue, and the transaction is stopped with a USTOP. The USTOP of the transaction is removed when the transaction or the class is started with a /START or UPD TRAN command.

Keyword combination rules include the following:

• MAXRGN>0 and SERIAL(Y) are mutually exclusive.
• PARLIM value 0 - 32767 and SERIAL(Y) are mutually exclusive.

SIDL

Specifies the system identification (SYSID) of the local system in a multiple-IMS system (MSC) configuration. The local system is the originating system to which responses are returned. The value can be a number from 1 to 2036. The local SYSID can be defined in any or all of the MSNAMEs or transactions.

The SIDL parameter is independent of the link type (CTC, MTM, TCP/IP, VTAM) specified on the TYPE= keyword of the MSPLINK macro statement.

Keyword combination rules include the following:

• FP(E) and SIDL are mutually exclusive, unless SIDL and SIDR are specified as a pair and are equal to the local system ID of this IMS.
• MSNAME and SIDL are mutually exclusive.
• SIDL value must be defined to this IMS.

SIDR

Specifies the system identification (SYSID) of the remote system in a multiple-IMS system (MSC) configuration. The remote system is the system on which the application program executes. The value can be a number from 1 to 2036. The remote SYSID specified must also be defined for an MSNAME.

The SIDR parameter is independent of the link type (CTC, MTM, TCP/IP, VTAM) specified on the TYPE= keyword of the MSPLINK macro statement.

Keyword combination rules include the following:

• FP(E) and SIDR are mutually exclusive, unless SIDL and SIDR are specified as a pair and are equal to the local system ID of this IMS.
• MSNAME and SIDR are mutually exclusive.
• SIDR value must be defined to this IMS.

SPASZ

Specifies the scratchpad area (SPA) size, in bytes, for a conversational transaction. The value can be a number from 16 and 32767.

Keyword combination rules include the following:

• CONV(N) and SPASZ are mutually exclusive.

SPATRUNC

Specifies the scratchpad area (SPA) truncation option of a conversational transaction. This defines whether the SPA data should be truncated or preserved across a program switch to a transaction that is defined with a smaller SPA.

When a conversation initially starts, and when a program is switched, the SPATRUNC option is checked and set or reset as specified. When the option is set, it remains set for the life of the conversation, or until a program switch occurs to a transaction that specifies the option is to be Reset.

When a program switch occurs, the truncated data option for the new transaction is first checked, and that specification is set for the conversation and is used for the SPA inserted into the output message. If the option is not specified for the new transaction, the option currently in effect for the conversation is used.

S

IMS preserves all of the data in the SPA, even when a program switch is made to a transaction that is defined with a smaller SPA. The transaction with the smaller SPA does not see the truncated data, but when the transaction switches to a transaction with a larger SPA, the truncated data is used.

R

The truncated data is not preserved.

Keyword combination rules include the following:

• CONV(N) and SPATRUNC are mutually exclusive.

TRANSTAT

Specifies whether transaction level statistics should be logged for message driven programs. If Y is specified, transaction level statistics are written to the log in a X'56FA' log record.

N

Transaction level statistics should not be logged.

Y

Transaction level statistics should be logged.

The TRANSTAT keyword on the UPDATE TRAN or UPDATE TRANDESC command gives the user the ability to override the system default or the current value of the TRANSTAT parameter. If the TRANSTAT keyword is omitted on the UPDATE TRAN or UPDATE TRANDESC command, the current transaction level statistics setting is unchanged.

WFI

Specifies the wait-for input option. This attribute does not apply to Fast Path transactions, which always behave as wait-for-input transactions.

N

This is not a wait-for-input transaction.

Y

This is a wait-for-input transaction. A message processing or batch processing application program that processes WFI transactions are scheduled and invoked normally. If the transaction to be processed is defined as WFI, the program is allowed to remain in main storage after it has processed the available input messages. The QC status code (no more messages) is returned to the program if the PROCLIM count (PLCT) is reached; a command is entered to change the status of the scheduled transaction, database, program, or class; commands relating to the databases used by the transaction are entered, or IMS is terminated with a checkpoint shutdown.

Keyword combination rules include the following:

• MODE(MULT) and WFI(Y) are mutually exclusive.

Usage notes

If all the attributes specified by the UPDATE command are already defined for the descriptor, no update is actually made, no descriptors are quiesced, no log record is created, and a completion code of zero is returned. This avoids unnecessary overhead when no action needs to be taken.

Descriptors exist for the life of the IMS unless they are deleted using a DELETE command. The descriptors are recoverable across an IMS warm start or emergency restart. Descriptors are lost if IMS is cold started, unless cold start imports definitions that were exported while IMS was up. Each descriptor is updated individually. Individual updating does not work like online change where either all descriptors are updated or no descriptors are updated.

The UPDATE TRANDESC command can be issued only through the OM API. This command applies to DB/DC and DCCTL systems.

This command is not valid on the XRF alternate, RSR tracker, or FDBR region. The UPDATE TRANDESC commands are not valid if online change for MODBLKS is enabled (DFSDFxxx or DFSCGxxx defined with MODBLKS=OLC, or MODBLKS not defined).

This command is recoverable.

If the descriptor being updated is the IMS-defined transaction descriptor (DFSDSTR1) the only attribute that can be changed is the DEFAULT attribute.

Output fields

Return, reason, and completion codes

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.

Errors unique to the processing of this command are returned as completion codes. The following table includes an explanation of the completion codes.

Table 4. Completion codes for the UPDATE TRANDESC command

Completion code	Completion code text	Meaning
0		Command completed successfully for transaction descriptor.
10	NO RESOURCES FOUND	Transaction descriptor name is invalid, or the wildcard parameter specified does not match any descriptor names.
17	ANOTHER CMD IN PROGRESS	Another command (such as DELETE or UPDATE) is in progress for this transaction descriptor. This could also mean this command, if the descriptor is specified by more than one specific or wildcard parameter.
19	CMTMODE=MULT/WFI=Y CONFLICT	Transaction descriptor update failed because commit mode multiple CMTMODE(MULT) option conflicts with the wait-for-input WFI(Y) option.
1B	CONV=Y/CMTMODE=MULT CONFLICT	Transaction descriptor update failed because the conversation CONV(Y) option conflicts with the commit mode multiple CMTMODE(MULT) option.
1E	CONV=N/SPASZ/SPATRUNC CONFLICT	Transaction descriptor update failed because the CONV(N) option conflicts with the SPA size or SPA truncation option.
1F	CONV=Y/RECOVER=N CONFLICT	Transaction descriptor update failed because the conversation CONV(Y) option conflicts with the nonrecoverable RECOVER(N) option.
27	NOT ALLOWED FOR DEFAULT DESCRIPTOR	Transaction descriptor update failed because the default descriptor cannot update any runtime resource definition attribute.
2F	FP=E/BMPTYPE=Y CONFLICT	Transaction descriptor update failed, because Fast Path exclusive FP(E) option conflicts with program defined as batch BMPTYPE(Y).
35	FP=E/EDITRTN CONFLICT	Transaction descriptor update failed because Fast Path exclusive FP(E) option conflicts with the edit routine EDITRTN.
36	FP=E/FP=N PGM CONFLICT	Transaction descriptor update failed because Fast Path exclusive FP(E) option conflicts with program defined as non-Fast Path FP(N).
38	NOT ALLOWED FOR A BMP	The UPDATE TRAN command is invalid for the resource because the PSB associated with the transaction descriptor is a BMP.
3A	FP=E OR P/MSC KEYWORD CONFLICT	Transaction descriptor update failed because Fast Path exclusive FP(E) or Fast Path potential FP(P) option conflicts with the MSC MSNAME, SIDR/SIDL option.
3B	FP/MSGTYPE=MULTSEG CONFLIC CONFLICT	Transaction descriptor update failed because Fast Path exclusive FP(E) or Fast Path potential FP(P) option conflicts with message type multiple segment MSGTYPE(MULTSEG) option.
3C	MAXRGN/PARLIM=65535 CONFLICT	Transaction descriptor update failed because maximum region count MAXRGN value conflicts with the parallel limit count PARLIM value 65535, which means parallel scheduling is disabled. MAXRGN > 0 is not allowed with PARLIM(65535).
3E	FP=N/FP=E PGM CONFLICT	Transaction descriptor update failed because non-Fast Path FP(N) option conflicts with program defined as Fast Path exclusive FP(E).
3F	FP=P/BMPTYPE=Y CONFLICT	Transaction descriptor update failed because Fast Path potential program FP(P) conflicts with the program defined as batch BMPTYPE(Y).
40	PARLIM/SCHDTYPE=SERIAL CONFLICT	The PARLIM cannot be changed for the resource because the PSB associated with the transaction is defined as does not have parallel scheduling.
41	FP=E OR P/RECOVER=N CONFLICT	Transaction descriptor update failed because Fast Path exclusive FP(E) or Fast Path potential FP(P) option conflicts with nonrecoverable RECOVER(N) option.
42	FP=E OR P/RESP=N CONFLICT	Transaction descriptor update failed because Fast Path exclusive FP(E) or Fast Path potential FP(P) option conflicts with response mode RESP(N) option.
48	NOT ALLOWED FOR IMS RESOURCE	The specified UPDATE command is not allowed for the IMS descriptor or resource. DFSDSTR1 is an example of an IMS descriptor. The only IMS descriptor attribute you can update is DEFAULT(Y).
49	INQ=N/RECOVER=N CONFLICT	Transaction descriptor update failed because non-inquiry INQ(N) option conflicts with nonrecoverable RECOVER(N) option.
4F	INVALID MAXRGN VALUE	Maximum region MAXRGN value is invalid.
5E	MAXRGN GT 0/SERIAL=Y CONFLICT	Transaction descriptor update failed because non-zero maximum region value conflicts with serial SERIAL(Y) option.
61	DFSBCB STORAGE ERROR.	DFSBCB storage could not be obtained.
6B	PARLIM/SERIAL=Y CONFLICT	Transaction descriptor update failed because the parallel limit PARLIM value conflicts with the serial SERIAL(Y) option.
6D	INVALID PROGRAM NAME
79	REMOTE/SIDR/SIDL/MSNAME CONFLICT	Transaction descriptor update failed because remote REMOTE(Y) option requires MSC keyword such as MSNAME or SIDR/SIDL.
8A	WILDCARD PARAMETER NOT SUPPORTED	A wildcard parameter was specified with DEFAULT(Y). Only one descriptor can be the default at one time.
1D7	IMPORT CHANGE LIST ERROR	The descriptor is in the process of being imported from the change list in the IMSRSC repository or was not successfully imported from the change list. The descriptor cannot be updated until it is successfully imported from the repository.