TRANSLATE

Translate resource table attribute values.

Warning: System commands are powerful as they provide information about the state of the system and allow changes to be made to it. System commands should be used only by authorized applications and users.

Activate security checks on commands by specifying the XCMD system initialization parameter and by ensuring that command security checking is active for the transaction (either by specifying CMDSEC(YES) on the TRANSACTION resource definition or by specifying ALWAYS on the CMDSEC system initialization parameter).

Command

Read syntax diagramSkip visual syntax diagramTRANSLATEOBJECT(data-value) ATTRIBUTE(data-value )FROMCV(data-value)TOCHAR(data-ref)FROMCHAR(data-value)TOCV(data-ref)THREAD(cpsm-token) RESPONSE(data-ref) REASON(data-ref)

Description

This command translates resource table attribute values that are maintained in an encoded form (such as EYUDA and CVDA values) between their internal coded format and an external display format.
  • If your program is written in REXX, you can use the TPARSE command to access a resource table record and translate its attribute values. However, if you use the ASIS option with TPARSE, attribute values are not translated into their external format; in that case, you would need to use TRANSLATE after using TPARSE to receive the formatted display values. For a description of the TPARSE command, see REXX functions and commands.
  • In a CICS® environment, the DFHVALUE function can return incompatible CVDA values for the following resource table attributes:
    Resource table Attribute value
    CONNECT RECOVSTATUS(NRS)
    IPCONN RECOVSTATUS(NRS)
    LIBRARY CRITSTATUS(CRITICAL)
    LOCTRAN RESSEC(RESSECEXT)
    PROGDEF API(CICSAPI)
    PROGRAM APIST(CICSAPI)
    PROGRAM LPASTAT(NOTSVA)
    PROGRAM LPASTAT(SVA)

    Because these CVDA values conflict with values used in CICS, CICSPlex SM must modify them to retain their uniqueness. CICSPlex SM adds either 8000 or 9000 to the value returned by DFHVALUE for each of these CICS CVDA attributes.

    If you want to translate any of these attributes, you must add either 8000 or 9000 to the value you received from DFHVALUE before presenting the attribute to CICSPlex SM.

Options

ATTRIBUTE(data-value)
Identifies the resource table attribute that is to be translated. This value must be the 1- to 12-character name of a valid attribute for the resource table.
FROMCHAR(data-value)
Specifies the 1- to 12-character value for the specified attribute.
FROMCV(data-value)
Specifies the 4-byte internal coded value for the specified attribute.
OBJECT(data-value)
Identifies the resource table to which the attribute being translated belongs. This value must be the 8-character name of a valid resource table.
REASON(data-ref)
Names a variable to receive the fullword reason value returned by this command.
RESPONSE(data-ref)
Names a variable to receive the fullword response value returned by this command.
THREAD(cpsm-token)
Identifies the API thread to be used for this operation. The cpsm-token value that identifies a thread is returned by the CONNECT command.
TOCHAR(data-ref)
Names a variable to receive the result of translating an internal coded value to the 1- to 12-character value for the specified attribute.
TOCV(data-ref)
Names a variable to receive the result of translating a character value to the 4-byte internal coded value for the specified attribute.

Conditions

The following is a list of the RESPONSE values that can be returned by the TRANSLATE command. The description of each RESPONSE includes a list of associated REASON values, if appropriate.
1024 OK
The command completed processing successfully.
1028 INVALIDPARM
An invalid parameter was detected. The parameter that is invalid is returned as the reason value:
  • 1280 THREAD
  • 1281 OBJECT
  • 1310 ATTRIBUTE
  • 1311 FROMCV
  • 1312 TOCHAR
  • 1313 FROMCHAR
  • 1314 TOCV

Check the command description for valid parameter syntax.

1029 FAILED
The command failed for one of the following reasons:
1331 ABENDED
Command processing abended.
1359 EXCEPTION
Command processing encountered an exceptional condition.
1030 ENVIRONERROR
An environment error occurred for one of the following reasons:
1321 SOCRESOURCE
A required resource that is owned by the CMAS is not available.
1357 NOSTORAGE
The application stub program could not obtain the necessary storage in the address space where the processing thread is running.
1358 NOSERVICE
The application stub program could not load the API service module.
1033 SERVERGONE
The CMAS to which the processing thread was connected is no longer active.
1034 NOTAVAILABLE
A not available condition occurred for one of the following reasons:
1334 CPSMAPI
The CMAS to which the processing thread is connected is not available for API processing.
1340 APITASK
The API control subtask is not active.
1035 VERSIONINVL
A version conflict occurred for one of the following reasons:
1335 NOTSUPPORTED
The version of the application stub program used for this command is not supported.
1336 NOTVSNCONN
The version of the application stub program used for this command is not the same as the version used with the CONNECT command.
1038 TABLEERROR
A resource table record is invalid for the following reason:
1354 INVALIDVER
The specified version of the resource table is not supported by CICSPlex SM.