UPDATE PGMDESC command

Updating a descriptor changes only the attributes explicitly specified on the UPDATE command. Attributes not specified retain their existing values. Any program 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-+--PGMDESC--NAME(---name-+-)------------------------>
   '-UPD----'                              

          .-,----------------------------.       
          V                              |       
>----SET(---+-BMPTYPE(-+-Y-+-)---------+-+-)-------------------->
            |          '-N-'           |         
            +-DEFAULT(Y)---------------+         
            +-DOPT(-+-N-+-)------------+         
            |       '-Y-'              |         
            +-FP(-+-E-+-)--------------+         
            |     '-N-'                |         
            +-GPSB(-+-N-+-)------------+         
            |       '-Y-'              |         
            +-LANG(-+-ASSEM--+-)-------+         
            |       +-COBOL--+         |         
            |       +-JAVA---+         |         
            |       +-PASCAL-+         |         
            |       '-PLI----'         |         
            +-RESIDENT(-+-N-+-)--------+         
            |           '-Y-'          |         
            +-SCHDTYPE(-+-PARALLEL-+-)-+         
            |           '-SERIAL---'   |         
            '-TRANSTAT(-+-N-+-)--------'         
                        '-Y-'                    

>--+----------------+------------------------------------------><
   '-OPTION(ALLRSP)-'   

Keywords

The following keywords are valid for the UPDATE PGMDESC command:

NAME

Specifies the 1-8 character name of the program 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.

BMPTYPE

BMP type option. Specifies whether the program executes in a BMP type region or not. A BMP type region can be a BMP region or a JBP region.

PSBs scheduled by DB2® stored procedures, by programs running under WebSphere® Application Server, and by other users of the ODBA interface may be defined with BMPTYPE Y or N.

Y

The program executes in a BMP type region. It can execute in an IMS™ BMP region or a JBP region. Any associated transactions are assigned normal and limit priority values of zero.

N

The program does not execute in a BMP type region. It may execute in an IMS TM MPP, JMP, or IFP region, or it may use either the ODBA or DRA interface. This specification should be used for programs running in IMS TM MPP, JMP, and IFP regions, or PSBs scheduled by CICS® programs using DBCTL and other users of the DRA interface. This is the default.

Keyword combination rules include the following:

• BMPTYPE(Y) and FP(E) are mutually exclusive.

DEFAULT(Y)

Specifies this descriptor as the default, which resets the existing default descriptor to DEFAULT(N). When a descriptor or resource 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 a program descriptor called DFSDSPG1, 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 program descriptor can be the default at one time, only one descriptor name can be specified with DEFAULT(Y).

DOPT

Specifies the dynamic option.

N

The PSB associated with this program is not located dynamically. The PSB must exist in ACBLIB, otherwise the program is set to a NOTINIT status, and cannot be scheduled.

Y

The PSB associated with this program is located dynamically. Each time the program associated with this PSB is scheduled, the latest copy of the PSB is loaded from ACBLIB. The PSB does not need to be in any data set defined for ACBLIB until it is actually required to process a transaction. A new version of the PSB can be genned in ACBLIB and is picked up the next time the PSB is scheduled. DOPT PSBs referencing DBDs that are missing from ACBLIB cannot be scheduled. When the program terminates, the PSB is deleted from the PSB pool.

Keyword combination rules include the following:

• DOPT(Y) and GPSB(Y) are mutually exclusive.
• DOPT(Y) and LANG(JAVA) is a valid combination.
• LANG is invalid with GPSB(N), except if DOPT(Y) and LANG(JAVA).
• LANG(JAVA), DOPT(Y), and GPSB(N) is a valid combination.
• RESIDENT(Y) and DOPT(Y) are mutually exclusive.
• SCHDTYPE(PARALLEL) and DOPT(Y) are mutually exclusive.

FP

Specifies the Fast Path option.

E

The program is a Fast Path-exclusive application program. This implicitly defines a wait-for-input (WFI) application program. Either a transaction or a routing code that can be assigned by the user Input Edit/Routing exit routine must be defined for the Fast Path-exclusive application, in order for this program to be usable.

N

The program is not a Fast Path-exclusive application program. When FP(N) is specified, any attempt to use Fast Path resources or commands will yield unpredictable results.

Keyword combination rules include the following:

• FP(E) requires Fast Path to be defined.
• LANG(JAVA) and FP(E) are mutually exclusive.
• BMPTYPE(Y) and FP(E) are mutually exclusive.

GPSB

Specifies the generated PSB option.

N

The PSB associated with the program is not generated by IMS. The PSB must exist in ACBLIB; otherwise the program is set to a NOTINIT status and cannot be scheduled.

Y

The PSB associated with the program is generated by IMS. It is not loaded from ACBLIB. The scheduling process of all environments generates a PSB containing an I/O PCB and an alternate modifiable PCB. You do not need to perform the PSBGEN and ACBGEN, thus eliminating I/O to the ACBLIB.

The generated PSB contains an I/O PCB named IOPCBbbb and a modifiable, alternate PCB named TPPCB1bb. With an alternate modifiable PCB, an application can use the CHNG call to change the output destination and send output to a destination other than the input destination.

Keyword combination rules include the following:

• DOPT(Y) and GPSB(Y) are mutually exclusive.
• DOPT(Y) and LANG(JAVA) is a valid combination.
• GPSB(Y) requires LANG.
• LANG is invalid with GPSB(N), except if DOPT(Y) and LANG(JAVA).
• LANG(JAVA), DOPT(Y), and GPSB(N) is a valid combination.
• RESIDENT(Y) and GPSB(Y) are mutually exclusive.

LANG

Specifies the language interface of the application program for a GPSB.

The LANG parameters and their meanings are identified in the following table.

LANG parameter	Meaning
ASSEM	Assembler
COBOL	COBOL
JAVA	Java™
PASCAL	Pascal
PLI	PL/I

Keyword combination rules include the following:

• LANG is invalid with GPSB(N), except if DOPT(Y) and LANG(JAVA).
• DOPT(Y) and LANG(JAVA) is a valid combination.
• LANG(JAVA), DOPT(Y), and GPSB(N) is a valid combination.
• FP(E) and LANG(JAVA) are mutually exclusive.

RESIDENT

Specifies the resident option.

N

The PSB associated with the program is made to be not resident in storage. The PSB is loaded at scheduling time.

Y

The PSB associated with the program is made to be resident in storage immediately. IMS loads the PSB and initializes it. The PSB is removed from the PSB pool, if applicable. A resident PSB is accessed in local storage, which eliminates I/O to retrieve the ACB.

Keyword combination rules include the following:

• DOPT(Y) and RESIDENT(Y) are mutually exclusive.
• GPSB(Y) and RESIDENT(Y) are mutually exclusive.

SCHDTYPE

Specifies whether this application program can be scheduled into more than one message region or batch message region simultaneously.

PARALLEL

The application program can be scheduled in multiple regions simultaneously.

SERIAL

The application program can be scheduled in only one region at a time.

Updating this attribute to SCHDTYPE(SERIAL) is rejected if a transaction referencing this program is defined with a parallel limit count other than 65535.

Keyword combination rules include the following:

• DOPT(Y) and SCHDTYPE(PARALLEL) are mutually exclusive.

TRANSTAT

Specifies whether transaction level statistics should be logged. The value specified has meaning only if the program is a JBP or a non-message driven BMP. 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 PGMDESC 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 PGMDESC command, the current transaction level statistics setting is unchanged for the program.

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. 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.

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

This command is not valid on the XRF alternate, RSR tracker, or FDBR region. The UPDATE PGMDESC 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 is the IMS-defined program descriptor (DFSDSPG1) the only attributes that can be updated are the DEFAULT (SET(DEFAULT(Y))) and the TRANSTAT (SET(TRANSTAT(Y|N|))) attributes.

Each descriptor is updated individually. Individual updating does not work like online change where either all descriptors are updated or no descriptors are updated.

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 PGMDESC command

Completion code	Completion code text	Meaning
0		Command completed successfully for program descriptor.
10	NO RESOURCES FOUND	Program 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 program descriptor. This could also mean this command, if the descriptor is specified by more than one specific or wildcard parameter.
29	DOPT=Y/RESIDENT=Y CONFLICT	Program descriptor update failed because dynamic DOPT(Y) option conflicts with resident RESIDENT(Y) option.
2A	DOPT=Y/PARALLEL CONFLICT	Program descriptor update failed because dynamic DOPT(Y) option conflicts with parallel schedule SCHDTYPE(PARALLEL) option.
2F	FP=E/BMPTYPE=Y CONFLICT	Program descriptor update failed because Fast Path exclusive FP(E) option conflicts with BMP type BMPTYPE(Y).
37	FP=E/LANG=JAVA CONFLICT	Program descriptor update failed because Fast Path exclusive FP(E) option conflicts with Java language LANG(JAVA).
40	PARLIM/SCHDTYPE=SERIAL CONFLICT	The SCHDTYPE value cannot be changed to SERIAL because a transaction that references the program has a PARLIM value that is something other than 65535. The program definition is not updated.
43	GPSB=Y/DOPT=Y CONFLICT	Program descriptor updated failed because generated PSB GPSB(Y) option conflicts with dynamic DOPT(Y) option.
46	GPSB=N/LANG CONFLICT	Generated PSB option N (GPSB(N)) conflicts with the language option (LANG()). The program definition is not updated.
47	GPSB=Y/RESIDENT=Y CONFLICT	Program descriptor update failed because generated PSB GPSB(Y) option conflicts with the resident RESIDENT(Y) option.
48	NOT ALLOWED FOR IMS RESOURCE	The specified UPDATE command is not allowed for the IMS descriptor or resource. DFSDSPG1 is an example of an IMS descriptor. The only IMS descriptor attribute you can update is DEFAULT(Y).
8A	WILDCARD PARAMETER NOT SUPPORTED	A wildcard parameter was specified with DEFAULT(Y). Only one descriptor can be the default at a time.
97	DOPT=Y/LANG CONFLICT	Program descriptor update failed because dynamic option DOPT(Y) conflicts with LANG specified. DOPT(Y) is only supported with LANG(JAVA).
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.