Convert Format of Service Information (QPDETCVT) API

The Convert Format of Service Information(QPDETCVT) API takes the data input and converts it to a string containing an XML object.

Authorities and Locks

Authority to use the API

No authorities needed.

Required Parameter Group

Receiver Variable

OUTPUT; CHAR(*)

The receiver variable that receives the information requested. The data returned will be a formatted XML string.

Length of receiver variable

INPUT; BINARY(4)

The size of the area to contain the information returned, in bytes.

This parameter must specify the size of the variable you use for the receiver variable parameter. If this parameter specifies a longer size, other parts of storage could be overwritten when the API returns the information.

To determine how much information the API actually returns in response to this call, see the bytes returned field in the receiver variable format. To determine how much information the API could return if space were available, see the bytes available field.

If the bytes available is greater than the length supplied, no XML data will be returned and the bytes returned field will be set to 8.

Format of receiver variable

INPUT; CHAR(8)

The format of the information passed back to the caller of this API. The possible format names are:

CVTR0100

The information returned to the caller of this API. For more information, see CVTR0100 Format for information to convert

Information to convert

INPUT; CHAR(*)

The data to be converted.

Format of information to convert

INPUT; CHAR(8)

The format of the information passed in the information to convert. The possible format names are:

CVTS0100	The information to convert and the receiver variable are for LIC Log data typically associated with the exit program specified in Start Watch (STRWCH) command or API. The format of the receiver variable will be described by the XSD file specified in the returned XML object.
CVTS0200	The information to convert and the receiver variable are for message data typically associated with the Start Watch (STRWCH) command or API exit program. The format of the receiver variable will be described by the XSD file specified in the returned XML object.
CVTS0300	The information to convert and the receiver variable are for message data typically associated with the Open List of Messages (QGYOLMSG) API or the List Nonprogram Messages (QMHLSTM) API. For more information, see CVTS0300 Format for information to convert. The format of the receiver variable will be described by the XSD file specified in the returned XML object.
CVTS0400	The information to convert and the receiver variable are for message data typically associated with the Open List of Job Log Messages (QGYOLJBL) API or the List Job Log Messages (QMHLJOBL) API. For more information, see CVTS0400 Format for information to convert. The format of the receiver variable will be described by the XSD file specified in the returned XML object.
CVTS0500	The information to convert and the receiver variable are for message data typically associated with the Open List of History Log Messages (QMHOLHST) API. For more information, see CVTS0500 Format for information to convert. The format of the receiver variable will be described by the XSD file specified in the returned XML object.
CVTS0600	The information to convert and the receiver variable are for Product Activity Log (PAL) data typically associated with the exit program specified in the Start Watch (STRWCH) command or the QSCSWCH API. The format of the receiver variable will be described by the XSD file specified in the returned XML object.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

CVTR0100 - Format for receiver variable

CVTS0100 - Format for LIC Log conversion (STRWCH command or QSCSWCH API)

CVTS0200 - Format for message conversion (STRWCH command or QSCSWCH API)

The following table shows the input for converting messages received from the Start Watch command or API to XML. Any data not available should be initialized with '00'x. For a detailed description of each field, see Field Descriptions.

CVTS0300 - Format for message conversion (QGYOLMSG API or QMHLSTM API)

The following table shows the input for converting messages received from the Open List of Messages in format LSTM0100 to XML. For a detailed description of each field, For a detailed description of each field, see Field Descriptions. Any data not available should be initialized with '00'x.

CVTS0400 - Format for message conversion (QGYOLJBL API or QMHLJOBL API)

The following table shows the input for converting messages received from the Open list of Joblog Messages in format OLJL0100 to XML. For a detailed description of each field, see Field Descriptions. Any data not available should be initialized with '00'x.

CVTS0500 - Format for message conversion (QMHOLHST)

The following table shows the input for converting messages received from the Open List of History Log Messages to XML. Any data not available should be initialized with '00'x. For a detailed description of each field, Field Descriptions.

CVTS0600 - Format for PAL conversion (STRWCH command or QSCSWCH API)

The following table shows the input for converting a PAL to XML. Any data not available should be initialized with '00'x. For a detailed description of each field, see Field Descriptions.

Field Descriptions

Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.

Bytes returned. The number of bytes of data returned.

CCSID conversion status indicator for data. The following values may be returned:

CCSID conversion status indicator for text. The following values may be returned:

Coded character set identifier (CCSID) for data. The coded character set identifier that the data is returned in. If a conversion error occurs or if the CCSID you requested the data to be converted to is 65535, the CCSID of the data is returned. If there is no *CCHAR replacement data, 65535 is returned. Otherwise the CCSID you wanted the data converted to is returned.

This only applies to the part of the replacement data that corresponds to a convertible character data type (*CCHAR).

For more information about message handler and its use of CCSIDs, see CCSID support for messages.

Coded character set identifier (CCSID) for text. The coded character set identifier that the message text is returned in. If a conversion error occurs or if the CCSID you requested the message text to be converted to is 65535, the CCSID that the message text is stored in is returned. Otherwise the CCSID you wanted your message text converted to is returned. If you do not want the message text converted before it is returned to you but you do want to know the CCSID that the message text is stored in, specify 65535 on the Coded character set identifier to return text and data in parameter. The CCSID that the message text is stored in is returned in the Coded character set identifier for text output field.

Compare against. The part of the message the data specified in message comparison data field was compared against. This field is set to blanks if zero was specified for the length of comparison data field. The possible values are:

Comparison data CCSID. The coded character set identifier (CCSID) of the message comparison data.

Data. The data associated with the specified identifier field.

Date sent. The date on which the message was sent, in CYYMMDD (century, year, month, and day) format.

Device name. The name of a physical device or program that has an entry in the log.

Device type. The number or word used to identify a product.

Displacement to fields. The displayment displacement, in bytes, from the beginning of the repeating information for each message variable to the beginning of the first repeating identifier field of the CVTS0300 or CVTS0400 format.

Displacement to the first level message or immediate text. The displacement, in bytes, from the beginning of this entry to the beginning of the First level message or immediate text of the CVTS0500 format. This can be 0 if there is no message text available.

Displacement to the message replacement text. The displacement, in bytes, from the beginning of this entry to the beginning of the replacement message text of the CVTS0500 format. This can be 0 if there is no message replacement text available.

Displacement to the next entry. The displacement, in bytes, from the beginning of the first message entry to the beginning of the next message entry. If there is no next entry, this field should be set to 0.

Displacement to the next field information. The displacement, in bytes, from the beginning of the first message entry to the beginning of the next repeating identifier field of the CVTS0300 format.

Exception ID. The exception that caused the Log entry to be requested. This is a 2-byte hexadecimal field formed by concatenating to the high-order 1-byte exception group number a low-order 1-byte exception subtype number. Exception identifier is binary zeros if the LIC Log entry was not requested as a result of an exception.

First level message or immediate text. The first level text of the message or the immediate text.

From user. The current user from which the message was sent.

Identifier field. The field returned. See QGYOLMSG - Open List of Messages, the Valid Field Identifiers for the list of valid field identifiers.

Job name. The name of the job that sent the message.

Job number. The job number (000001-999999) to further qualify the job name and user name of the job that sent the message

Job user name. The user name of the job that sent the message.

Length of comparison data. The length of the user specified text which was compared against the message or LIC log or PAL event data.

Length of data. The length of the data returned in the data field, in bytes. If no data is returned, this value will be set to 0.

Length of field information. The total length of information in this field, in bytes.

Length of entry. The length, in bytes, of this entry. This length can be used to access the next entry.

Length of field information. The total length of information in this field, in bytes.

Length of fixed header. The total length of fixed header information, in bytes. The possible values are:

Length of message replacement data. The length of the message replacement data, in bytes.

Length of receiving procedure name. The length of the procedure the message was sent to when the message was sent to a procedure within an ILE program. This field is set to zero if the message was sent to an original program model (OPM) program or when the message is sent to a nonprogram message queue.

Length of sending procedure name. The length of the procedure sending the message when the message was sent from a procedure within an ILE program. This field is set to zero if the message was sent from an original program model (OPM) program.

Length of the first level message or immediate text. The length of the first level message or immediate text returned, in bytes.

Length of watch information. The length of the Information to convert parameter , including the 4-byte length of this field, associated with the data in format CVTS0100 or format CVTS0200.

LIC job name. The name of the job which requested the Log entry. LIC job name is blank (hex 40s) if the Log entry was not requested by a job.

LIC job number. The job number (000001-999999) to further qualify the job name and user name of the job which requested the LIC Log entry. LIC job number is blank (hex 40s) if the LIC Log entry was not requested by a job.

LIC job user name. The user name of the job which requested the LIC Log entry. LIC user name is blank (hex 40s) if the LIC Log entry was not requested by a job.

LIC log compare against. The part of the LIC log the data specified in LIC log comparison data field was compared against. This field is set to blanks if zero was specified for the length of comparison data field. The possible values are:

LIC log compare against specified. The character indicating if the LIC log compare against field was specified. The possible values are:

LIC Log comparison data. The user specified text string used to compare against the entry data of the watched for log entry. This is an optional field.

LIC Log identifier. The LIC Log entry identifier of the LIC Log that occurred. The LIC Log entry identifier is binary zeros if the entry was not added to the LIC Log by the time this event was signalled.

LIC Log major code. The major code of the LIC Log that occurred.

LIC Log minor code. The minor code of the LIC Log that occurred.

LIC Log timestamp. The binary timestamp of when the entry was requested to be added to the LIC Log. The format for this field is the system time-stamp format.

LIC module compile binary timestamp. The binary timestamp of when the LIC module was compiled. The format for this field is the system time-stamp format.

LIC module entry point name. The name of the entry point which requested the LIC Log entry. If the entry point name is greater than 128 characters, the LIC module entry point name is truncated to 128 characters.

LIC module name. The name of the module which requested the LIC Log entry. If the module name is greater than 48 characters, the LIC module name is truncated to 48 characters.

LIC module offset. The byte offset into the LIC module text which requested the LIC Log entry.

LIC module RU name. The replaceable unit name of the module which requested the LIC Log entry. LIC module RU name is always in upper case EBCDIC.

Log identifier. The unique identifier that ties together all data related to a single error condition.

Message comparison data. The user specified text string used to compare against the entry data of the watched for message ID.

Message file library. The name of the library containing the message file.

Message file library specified at send time. The name of the library containing the message file as specified when the message was sent. If *CURLIB or *LIBL was specified for the library when the message was sent, that value is returned as the library here.

Message file name. The name of the message file that was used to send the message.

Message ID. The identifier of the message that occurred.

Message identifier. The identifying code of the message listed. If an immediate message is listed, this field is set to blanks.

Message key. The message reference key of the message that occurred. This field is set to blanks if *JOBLOG is specified for the message queue name.

Message queue. The name of the message queue where the message was listed.

Message queue library. The name of the library where the message queue is located. This field is set to blanks if *JOBLOG is specified for the message queue name.

Message queue library used. The actual library that contains the message queue.

Message queue name. The name of the message queue where the message was sent. The following special values are accepted:

Message replacement data. The values for substitution variables in the message sent.

Message severity. The severity code, ranging from 0 through 99, of the message. If not specified, 0 will be used.

Message timestamp. The timestamp of when the message was sent. The format for this field is the system time-stamp format.

Message type. The type of message listed. The possible values and their meanings follow:

Microseconds. The microseconds part of the time sent.

Model. The numbers or letters used to identify the feature level of a product with a given type (for example, Model A or Model 1).

Number of fields. The number of identifier fields provided to the application

Number of messages to convert. The number of messages provided to the application

Offset to comparison data. The offset to the field that holds the comparison data. If there was no comparison data, this field should be set to 0.

Offset to first message. The offset , in bytes, from the beginning of the message information to convert variable to the beginning of the first repeating message entry of the CVTS0300 or CVTS0400 format.

Offset to message replacement data. The offset to the field that holds the replacement data.

Offset to receiving procedure name. The offset to the field that holds the procedure the message was sent to when the message was sent to a procedure within an ILE program. This field is set to zero if the message was sent to an original program model (OPM) program or when the message is sent to a nonprogram message queue.

Offset to sending procedure name. The offset to the field that holds the procedure sending the message when the message was sent from a procedure within an ILE program. This field is set to zero if the message was sent from an original program model (OPM) program.

Offset where comparison data was found. The offset in the message replacement data, the sending program name or the receiving program name, where the message comparison data was found. This field is set to zero if zero was specified for the length of comparison data field.

PAL timestamp. The timestamp of when the PAL entry was added. The format for this field is the system time-stamp format. The Convert Date and Time Format (QWCCVTDT) API can be used to convert a time-stamp value to character format.

Receiving module name. The name of the module receiving the message when the message was sent to a procedure within an ILE program. If the message was sent to an original program model (OPM) program, this field is set to blanks. This field will be blank when the message is sent to a nonprogram message queue.

Receiving procedure name. The name of the procedure the message was sent to when the message was sent to a procedure within an ILE program. A nested procedure name has each procedure name separated by a colon. The outermost procedure name is identified first followed by the procedures it contains. The innermost procedure is identified last in the string.

Receiving program name. The name of the program the message was sent to, or the Integrated Language Environment^® (ILE) program name that contains the procedure receiving the message. This field will be blank when the message is sent to a nonprogram message queue.

Reference code. The code that identifies the unique condition for logging the PAL entry.

Replacement data CCSID. The coded character set identifier (CCSID) that the message data is in. This only applies to the part of the replacement data that corresponds to a convertible character data type (*CCHAR). All other replacement data has not be converted and can be considered to have a CCSID of 65535. If there is no *CHAR replacement data, this field may be set to 65535.

For more information about message handler and its use of CCSIDS, see CCSIDS: Message Support in the Globalization topic. For more information about the *CCHAR field type, see the Add Message Description (ADDMSGD) command.

Reserved. A reserved field. This field must be set to hexadecimal or binary zero.

Resource name. The name of a physical device that has an entry in the log. A resource name is assigned at first by the system, but may have been changed to a new value by a user.

Secondary code. The code for the failing condition (for example, IOP return code, processor step code, program return code, or major minor code).

Sending module name. The name of the module the sending message when the sender is a procedure within an ILE program.

Sending procedure name. The name of the procedure sending the message when the sender is a procedure within an ILE program. A nested procedure name has each procedure name separated by a colon. The outermost procedure name is identified first followed by the procedures it contains. The innermost procedure is identified last in the string.

Sending program name. The program name or ILE program name that contains the procedure sending the message.

Sending user profile. The name of the user profile that the thread was running under when the message was sent. For jobs that swap user profiles, this user profile name and the job user name can be different.

Sequence. The numbers assigned to the entries in the log that indicate the sequence in which the entries were added. The highest number is the most recent.

Serial number. The number assigned to a part or machine type at the time of manufacture.

Server type. The type of server that requested the LIC Log entry. Server type is blank (hex 40s) if the LIC Log entry was not requested by a server.

Status of data. The status of the data listed for this message. Possible values and their meanings follow:

This field is applicable to the field identifiers that are retrieved from the message file for a stored message. A description of the action that occurs for specific field identifiers when the status of data field is not blank follows:

This field is also applicable to the various sending information fields (identifiers 0601, 0603) when a problem is encountered while attempting to retrieve this information. When one of these fields cannot be retrieved from the message:

• The status of data field is set to N.
• The length of data field is set to 0.

The status of data field is always blank for the other field identifiers. The length of data field is zero.

Symbolic message type. The type assigned to the message when it was sent. The possible values are:

System reference code. The code that identifies a unique logging condition. The system reference code is made up of the first four digits of the translate table ID followed by the four digits of the reference code.

Table ID. The identifier of the table that identifies a group of reference codes.

Target job name. The name of the job the message was sent to. This field is set to blanks, unless *JOBLOG is specified for the message queue name field. The target job name and sending job name will be the same, unless a message was sent from one job to a different job.

Target job number. The job number (000001-999999) to further qualify the job name and user name of the job the message was sent to. This field is set to blanks, unless *JOBLOG is specified for the message queue name field. The target job name and sending job name will be the same, unless a message was sent from one job to a different job.

Target job user name. The user name of the job the message was sent to. This field is set to blanks, unless *JOBLOG is specified for the message queue name field. The target job name and sending job name will be the same, unless a message was sent from one job to a different job.

Task name. The name of the task which requested the LIC Log entry. Task name is blank (hex 40s) if the LIC Log entry was not requested by a task.

TDE number. The number of the task dispatching element (TDE) which requested the LIC Log entry.

Thread ID. The thread which requested the LIC Log entry. Thread identifier is binary zeros if the LIC Log entry was not requested by a thread.

Time sent. The time at which the message being listed was sent, in HHMMSS (hour, minute, and second) format.

Type of data. The type of data returned.

XML data. The XML data being returned.

XML data length. The length of the XML object being returned.

Error Messages

The following messages may be sent from this function:

[ Back to top | Problem Management APIs | APIs by category ]