UPDATE RTC command
Use the UPDATE RTC command to update Fast Path routing codes. A Fast Path routing code can be used by the Fast Path Input Edit/Routing Exit Routine (DBFHAGU0) to route a transaction to a different application program for processing.
Subsections:
Environment
The following table lists the environments (DB/BC, DBCTL, and DCCTL) in which you can use the commands and keywords.
| Command / Keywords | DB/DC | DBCTL | DCCTL |
|---|---|---|---|
| UPDATE RTC | X | X | |
| NAME | X | X | |
| OPTION | X | X | |
| SET | X | X | |
| START | X | X | |
| STOP | X | X |
Syntax
.-,----. V | >>-+-UPDATE-+--RTC--NAME(---name-+-)----------------------------> '-UPD----' >--+-START(Q)--------------------+--+----------------+--------->< +-STOP(Q)---------------------+ '-OPTION(ALLRSP)-' | .-,----------------. | | V | | '-SET(---+-INQ(-+-N-+-)-+-+-)-' | '-Y-' | '-PGM(name)----'
Keywords
The following keywords are valid for the UPDATE RTC command:
- NAME
- Specifies the 1-8 character name of the routing code. 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 resource names that are processed. For NAME(*), command responses are returned only for the resource names that resulted in an error. OPTION(ALLRSP) can be specified with NAME(*) to obtain the command responses for all the resource 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 resources that are processed on the command. The default action is to return response lines only for the resources 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.
- INQ
- Specifies the inquiry option.
- N
- This is not an inquiry routing code.
- Y
- This is an inquiry routing code. Any message associated with the routing code is an inquiry transaction. This option should be specified only for programs that do not cause a change to a database. Programs are prohibited from issuing Insert, Delete, or Replace calls to a database when processing an inquiry transaction.
Updating this attribute quiesces the routing code for the duration of command processing.
- PGM
-
The name of the application program associated with the routing code. The program must exist and be defined with a BMPTYPE of N.
Updating this attribute quiesces the routing code for the duration of command processing.
- START
- Specifies attributes that are to be started.
- Q
- Starts queuing of messages.
- STOP
- Specifies attributes that are to be stopped.
- Q
- Stops queuing of messages.
Usage notes
Resources exist for the life of the IMS™ unless they are deleted using a DELETE command. Resources are recoverable across an IMS warm start or emergency restart. Resources are lost if IMS is cold started, unless cold start imports definitions that were exported while IMS was up.
The UPDATE RTC command can be issued only through the OM API. Fast Path must be installed on the system. 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 RTC commands specified with SET() 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.
The UPDATE RTC command changes a MODBLKS routing code to dynamic, if the INQ or PGM attribute is changed.
- Check for work in progress with a QRY RTC SHOW(WORK) command and either wait for the work to finish or address the work in progress. See the output fields for the QUERY RTC command for examples of work that might cause the delete to fail. Examples of work include a command in progress for the routing code or the routing code is active.
- The routing code cannot be updated if the program is scheduled. If the program is scheduled, you must stop the region before you issue the UPDATE RTC command.
Runtime resource definition attributes include the following: INQ and PGM. If all the attributes specified by the UPDATE command are already defined for the resource, no update is actually made, no resources are quiesced, no log record is created, and a completion code of zero is returned.
The following routing code attributes cannot be updated if online change for MODBLKS is enabled: INQ, PGM.
Output fields
- Short label
- Contains the short label generated in the XML output.
- Keyword
- Identifies keyword on the command that caused the field to be generated. N/A appears for output fields that are always returned. error appears for output fields that are returned only in case of an error.
- Meaning
- Provides a brief description of the output field.
| Short label | Keyword | Meaning |
|---|---|---|
| CC | N/A | Completion code. |
| CCTXT | error | Completion code text that briefly explains the non-zero completion code. |
| ERRT | error | Error text with diagnostic information. Error text can be returned for a non-zero completion code and contains information that further explains the completion code. |
| MBR | N/A | IMSplex member that built the output line. |
| RTC | RTC | Routing code name. |
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.
| Return code | Reason code | Meaning |
|---|---|---|
| X'00000000' | X'00000000' | Command completed successfully. The command output contains a line for each resource, accompanied by its completion code. If NAME(*) is specified without OPTION(ALLRSP), no output lines are returned. See the completion code table for details. |
| X'00000008' | X'00002008' | Required keywords were not specified. |
| X'00000008' | X'00002123' | Invalid program name. |
| X'00000008' | X'00002048' | Invalid SET attribute. |
| X'0000000C' | X'00003000' | Command was successful for some resources but failed for others. The command output contains a line for each resource, accompanied by its completion code. If NAME(*) is specified without OPTION(ALLRSP), only resources with non-zero completion codes are returned. See the completion code table for details. |
| X'00000010' | X'00003004' | Command was not successful for any of the resources. The command output contains a line for each resource, accompanied by its completion code. See the completion code table for details. |
| X'00000010' | X'0000400C' | Command is not valid on the XRF alternate. |
| X'00000010' | X'00004014' | Command is not valid on the RSR tracker. |
| X'00000010' | X'00004024' | No Fast Path defined. |
| X'00000010' | X'00004120' | Online change phase is in progress. |
| X'00000010' | X'00004300' | Command is not allowed because online change for MODBLKS is enabled (DFSDFxxx or DFSCGxxx defined with MODBLKS=OLC, or MODBLKS not defined). |
| X'00000010' | X'0000431C' | Program is quiesced. Cannot quiesce program. |
| X'00000014' | X'00005004' | DFSOCMD response buffer could not be obtained. |
| X'00000014' | X'00005008' | DFSPOOL storage could not be obtained. |
| X'00000014' | X'0000500C' | AWE could not be obtained. |
Errors unique to the processing of this command are returned as completion codes. The following table includes an explanation of the completion codes.
| Completion code | Completion code text | Meaning |
|---|---|---|
| 0 | Command completed successfully for routing code. | |
| 10 | NO RESOURCES FOUND | Routing code name is invalid, or the wildcard parameter specified does not match any resource names. |
| 17 | ANOTHER CMD IN PROGRESS | Another command (such as DELETE or UPDATE) is in progress for this routing code. This could also mean this command, if the resource is specified by more than one specific or wildcard parameter. Or, the routing code is updating the program name and another command is in progress for the program. |
| 39 |  FP=E TRAN FOR
RTC EXISTS |
The routing code was created by IMS for a Fast Path exclusive transaction and cannot be updated with the UPDATE RTC command. The attributes of the routing code can be updated only with the UPDATE TRAN command for the Fast Path exclusive transaction. |
| 61 | DFSBCB STORAGE ERROR | DFSBCB storage error. Could not get storage for RCTE control block. |
| 73 | PROGRAM SCHEDULED | Program is scheduled. |
| 7A | RTC/FP=N PGM
CONFLICT |
Program specified is not Fast Path exclusive. |
| 90 | INTERNAL ERROR | Internal error. |
| 99 | NOT INITIALIZED | Routing code update failed because the routing code is not initialized. QUERY RTC STATUS(NOTINIT) displays the reason why the routing code is not initialized, for example, the associated program is not defined. Correct the definition error and issue the UPD RTC START(Q) command to initialize the routing code. |
| 1D7 |
IMPORT
CHANGE LIST ERROR |
The resource 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 resource cannot
be updated until it is successfully imported from the repository. |
Examples
The following are examples of the UPDATE RTC command:
Example 1 for UPDATE RTC command
UPD RTC NAME(BADNAME,FPTRN02,SMQFP7*,BAD*) SET(PGM(DBFSAMP3))Response for: UPD RTC NAME(BADNAME,FPTRN02,SMQFP7*,BAD*) SET(PGM(DBFSAMP3))
RtcName MbrName CC CCText
BAD* IMS1 10 NO RESOURCES FOUND
BADNAME IMS1 10 NO RESOURCES FOUND
FPTRN02 IMS1 0
SMQFP7A IMS1 0
SMQFP7B IMS1 0
SMQFP7C IMS1 0
SMQFP71 IMS1 0
SMQFP72 IMS1 0
SMQFP73 IMS1 0 CMD(UPDATE RTC NAME(BADNAME,FPTRN02,SMQFP7*,BAD*) SET(PGM(DBFSAMP3)))<imsout>
<ctl>
<omname>OM1OM </omname>
<omvsn>1.3.0</omvsn>
<xmlvsn>20 </xmlvsn>
<statime>2006.311 23:50:02.663055</statime>
<stotime>2006.311 23:50:02.663790</stotime>
<staseq>BFAC125257C8FB80</staseq>
<stoseq>BFAC125257F6E500</stoseq>
<rqsttkn1>USRT011 10155002</rqsttkn1>
<rc>0200000C</rc>
<rsn>00003008</rsn>
<rsnmsg>CSLN054I</rsnmsg>
<rsntxt>None of the clients were successful.</rsntxt>
</ctl>
<cmderr>
<mbr name="IMS1 ">
<typ>IMS </typ>
<styp>DBDC </styp>
<rc>0000000C</rc>
<rsn>00003000</rsn>
<rsntxt>At least one request successful</rsntxt>
</mbr>
</cmderr>
<cmd>
<master>IMS1 </master>
<userid>USRT011 </userid>
<verb>UPD </verb>
<kwd>RTC </kwd>
<input>UPD RTC NAME(BADNAME,FPTRN02,SMQFP7*,BAD*) SET(PGM(DBFSAMP3))
</input>
</cmd>
<cmdrsphdr>
<hdr slbl="RTC" llbl="RtcName" scope="LCL" sort="a" key="1" scroll="no"
len="8" dtype="CHAR" align="left" />
<hdr slbl="MBR" llbl="MbrName" scope="LCL" sort="a" key="2" scroll="no"
len="8" dtype="CHAR" align="left" />
<hdr slbl="CC" llbl="CC" scope="LCL" sort="n" key="0" scroll="yes"
len="4" dtype="INT" align="right" />
<hdr slbl="CCTXT" llbl="CCText" scope="LCL" sort="n" key="0"
scroll="yes" len="32" dtype="CHAR" align="left" skipb="yes" />
</cmdrsphdr>
<cmdrspdata>
<rsp>RTC(BADNAME ) MBR(IMS1) CC( 10) CCTXT(NO RESOURCES FOUND) </rsp>
<rsp>RTC(FPTRN02 ) MBR(IMS1) CC( 0) </rsp>
<rsp>RTC(SMQFP7A ) MBR(IMS1) CC( 0) </rsp>
<rsp>RTC(BAD* ) MBR(IMS1) CC( 10) CCTXT(NO RESOURCES FOUND) </rsp>
<rsp>RTC(SMQFP7B ) MBR(IMS1) CC( 0) </rsp>
<rsp>RTC(SMQFP7C ) MBR(IMS1) CC( 0) </rsp>
<rsp>RTC(SMQFP71 ) MBR(IMS1) CC( 0) </rsp>
<rsp>RTC(SMQFP72 ) MBR(IMS1) CC( 0) </rsp>
<rsp>RTC(SMQFP73 ) MBR(IMS1) CC( 0) </rsp>
</cmdrspdata>
</imsout>Explanation: The UPDATE RTC command is issued to update the program for several routing codes. The update completed successfully for most of the routing codes, as shown by completion code 0. The update fails for routing code BADNAME and for parameter BAD* with completion code 10 because routing code BADNAME does not exist and no routing code name starts with BAD.