system i: programming problem management...

System i

Programming

Problem Management APIs

Version 6 Release 1

��

Note

Before using this information and the product it supports, read the information in “Notices,” on

page 231.

This edition applies to version 6, release 1, modification 0 of IBM i5/OS (product number 5761-SS1) and to all

subsequent releases and modifications until otherwise indicated in new editions. This version does not run on all

reduced instruction set computer (RISC) models nor does it run on CISC models.

© Copyright International Business Machines Corporation 1998, 2008.

US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract

with IBM Corp.

Contents

Problem Management APIs . . . . . . 1

Filtering . . . . . . . . . . . . . . . . 1

Working with a Problem . . . . . . . . . . 1

Key Groups . . . . . . . . . . . . . . . 1

APIs . . . . . . . . . . . . . . . . . 1

Monitoring APIs . . . . . . . . . . . . . 1

End Watch (QSCEWCH) API . . . . . . . . . 2

Authorities and Locks . . . . . . . . . . 2

Required Parameter Group . . . . . . . . 3

Error Messages . . . . . . . . . . . . 3

Start Watch (QSCSWCH) API . . . . . . . . . 3



Optional Parameter Group 1 . . . . . . . . 6


Format for message information . . . . . . . 7

Format for LIC log information . . . . . . . 7

Format for PAL information . . . . . . . . 7

Field Descriptions . . . . . . . . . . . 8

Error Messages . . . . . . . . . . . . 12

Start Watch Command or API Exit Program

(QPDETWCH) API . . . . . . . . . . . . 13



Problem Determination APIs . . . . . . . . 14

Qp0zDump()—Dump Formatted Storage Trace Data 15

Parameters . . . . . . . . . . . . . 15

Authorities . . . . . . . . . . . . . 16

Return Value . . . . . . . . . . . . . 16

Error Conditions . . . . . . . . . . . . 16

Usage Notes . . . . . . . . . . . . . 16

Related Information . . . . . . . . . . 16

Example . . . . . . . . . . . . . . 16

Trace Output: . . . . . . . . . . . . . 17

Qp0zDumpStack()—Dump Formatted Stack Trace

Data . . . . . . . . . . . . . . . . . 18

Parameters . . . . . . . . . . . . . 19

Return Value . . . . . . . . . . . . . 19


Usage Notes . . . . . . . . . . . . . 19


Example . . . . . . . . . . . . . . 20

Qp0zDumpTargetStack()—Dump Formatted Stack

Trace Data of the Target Thread . . . . . . . 22

Parameters . . . . . . . . . . . . . 22

Authorities . . . . . . . . . . . . . 22

Return Value . . . . . . . . . . . . . 22


Usage Notes . . . . . . . . . . . . . 23


Example . . . . . . . . . . . . . . 23

Trace Output: . . . . . . . . . . . . . 24

Qp0zLprintf()—Print Formatted Job Log Data . . . 25

Parameters . . . . . . . . . . . . . 26

Authorities . . . . . . . . . . . . . 26

Return Value . . . . . . . . . . . . . 26


Usage Notes . . . . . . . . . . . . . 26


Example . . . . . . . . . . . . . . 26

Job Log Output: . . . . . . . . . . . . 27

Qp0zUprintf()—Print Formatted User Trace Data . . 28

Parameters . . . . . . . . . . . . . 28

Authorities . . . . . . . . . . . . . 29

Return Value . . . . . . . . . . . . . 29


Usage Notes . . . . . . . . . . . . . 29


Example . . . . . . . . . . . . . . 30

Join Trace (QSCJOINT) API . . . . . . . . . 30



Error Messages . . . . . . . . . . . . 31

Problem Logging APIs . . . . . . . . . . . 32

Add Problem Log Entry (QsxAddProblemLogEntry)

API . . . . . . . . . . . . . . . . . 32



Rules for Key Usage . . . . . . . . . . 33

Error Messages . . . . . . . . . . . . 36

Change Problem Log Entry

(QsxChangeProblemLogEntry) API . . . . . . 36



Format of the Keys . . . . . . . . . . . 37


Error Messages . . . . . . . . . . . . 42

Create Problem Log Entry

(QsxCreateProblemLogEntry) API . . . . . . . 43



Format of the Keys . . . . . . . . . . . 44


Error Messages . . . . . . . . . . . . 48

Delete Problem Log Entry

(QsxDeleteProblemLogEntry) API . . . . . . . 48



Format of the Key Groups . . . . . . . . 49


Error Messages . . . . . . . . . . . . 50

End Problem Log Services

(QsxEndProblemLogServices) API . . . . . . . 50


Required Parameter . . . . . . . . . . 51

Error Messages . . . . . . . . . . . . 51

Log Software Error (QPDLOGER) API . . . . . 51





Usage Notes . . . . . . . . . . . . . 54

© Copyright IBM Corp. 1998, 2008 iii

Error Messages . . . . . . . . . . . . 55

Report Software Error (QpdReportSoftwareError)

API . . . . . . . . . . . . . . . . . 55



Problem Description Records Format . . . . . 56


Keys . . . . . . . . . . . . . . . . 56

Formats of Specific Problem Description Records 57


Usage Notes . . . . . . . . . . . . . 64

Error Messages . . . . . . . . . . . . 65

Retrieve Problem Log Entry

(QsxRetrieveProblemLogEntry) API . . . . . . 65



Format of the Key Groups . . . . . . . . 66


Error Messages . . . . . . . . . . . . 67

Start Problem Log Services

(QsxStartProblemLogServices) API . . . . . . . 68


Required Parameter . . . . . . . . . . 68

Error Messages . . . . . . . . . . . . 69

Work with Problem (QPDWRKPB) API . . . . . 69



Optional Parameter Group . . . . . . . . 71

Error Messages . . . . . . . . . . . . 71

QTRC Trace APIs . . . . . . . . . . . . 72

QtrcGetActiveLevel()—Get Active Trace Level . . . 73

Parameters . . . . . . . . . . . . . 74


Return Value . . . . . . . . . . . . . 74


Error Messages . . . . . . . . . . . . 74

Usage Notes . . . . . . . . . . . . . 74


Example . . . . . . . . . . . . . . 75

QtrcWriteStack()—Write Call Stack Trace Data . . . 76

Parameters . . . . . . . . . . . . . 76


Return Value . . . . . . . . . . . . . 77


Error Messages . . . . . . . . . . . . 77

Usage Notes . . . . . . . . . . . . . 77


Example . . . . . . . . . . . . . . 78

QtrcWriteHexDumpF()—Write Hexadecimal Dump

Formatted Trace Data . . . . . . . . . . . 79

Parameters . . . . . . . . . . . . . 79


Return Value . . . . . . . . . . . . . 81


Error Messages . . . . . . . . . . . . 81

Usage Notes . . . . . . . . . . . . . 81


Example . . . . . . . . . . . . . . 82

QtrcWriteHexDump()—Write Hexadecimal Dump

Trace Data . . . . . . . . . . . . . . . 83

Parameters . . . . . . . . . . . . . 83


Return Value . . . . . . . . . . . . . 84


Error Messages . . . . . . . . . . . . 84

Usage Notes . . . . . . . . . . . . . 84


Example . . . . . . . . . . . . . . 85

QtrcWriteText()—Write Text Trace Data . . . . . 86

Parameters . . . . . . . . . . . . . 87


Return Value . . . . . . . . . . . . . 88


Error Messages . . . . . . . . . . . . 88

Usage Notes . . . . . . . . . . . . . 88


Example . . . . . . . . . . . . . . 89

QtrcWriteTextPPrintF()—Write Text Trace Data

Using Pointer-based Print Formatted . . . . . . 89

Parameters . . . . . . . . . . . . . 90


Return Value . . . . . . . . . . . . . 91


Error Messages . . . . . . . . . . . . 92

Usage Notes . . . . . . . . . . . . . 92


Example . . . . . . . . . . . . . . 93

QtrcWriteTextPrintF()—Write Text Trace Data Using

Print Formatted . . . . . . . . . . . . . 94

Parameters . . . . . . . . . . . . . 94


Return Value . . . . . . . . . . . . . 95


Error Messages . . . . . . . . . . . . 96

Usage Notes . . . . . . . . . . . . . 96


Example . . . . . . . . . . . . . . 96

QtrcWriteTextVPrintF()—Write Text Trace Data

Using Variable Argument List Print Formatted . . 98

Parameters . . . . . . . . . . . . . 99

Authorities and Locks . . . . . . . . . 100

Return Value . . . . . . . . . . . . 100

Error Conditions . . . . . . . . . . . 100

Error Messages . . . . . . . . . . . . 100

Usage Notes . . . . . . . . . . . . . 100


Example . . . . . . . . . . . . . . 101

Service APIs . . . . . . . . . . . . . . 103

Change Contact Information (QEDCHGIN) API 103



CNTC0100 Format . . . . . . . . . . . 104


Error Messages . . . . . . . . . . . . 109

Collect Hung Job Service Documentation

(QPDETHNG) API . . . . . . . . . . . 109



Error Messages . . . . . . . . . . . . 110

Convert Format of Service Information

(QPDETCVT) API . . . . . . . . . . . . 110


iv System i: Programming Problem Management APIs


CVTR0100 - Format for receiver variable . . . 112

CVTS0100 - Format for LIC Log conversion

(STRWCH command or QSCSWCH API) . . . 113

CVTS0200 - Format for message conversion



(QGYOLMSG API or QMHLSTM API) . . . . 115


(QGYOLJBL API or QMHLJOBL API) . . . . 116


(QMHOLHST) . . . . . . . . . . . . 117

CVTS0600 - Format for PAL conversion



Error Messages . . . . . . . . . . . . 127

Filter Problem (QSXFTRPB) API . . . . . . . 128



Format for the Problem Log Identifier . . . . 128


Error Messages . . . . . . . . . . . . 129

Retrieve Contact Information (QEDRTVCI) API . . 129



CNTI0100 Format . . . . . . . . . . . 130


Error Messages . . . . . . . . . . . . 134

Retrieve Policy Data (QPDETRTV) API . . . . . 134



Format of Data Returned . . . . . . . . 135


Error Messages . . . . . . . . . . . . 138

Retrieve Service Attributes (QESRSRVA) API . . . 138



Receiver Variable Format . . . . . . . . 139


Service Attribute Template Format . . . . . 140


Service Attributes Format . . . . . . . . 141

Key 1—Automatic Problem Analysis . . . . 141


Key 2—Automatic Problem Reporting . . . . 141


Key 3—Service Provider to Report Problem . . 142


Key 4—PTF Install Type . . . . . . . . . 142


Key 5—Critical Message Recipients . . . . . 142


Key 6—Send Data Packets . . . . . . . . 143


Key 7—Copy PTFs . . . . . . . . . . 143


Key 8—PTF group levels . . . . . . . . 144


Key 9—ECS message queue . . . . . . . 144


Key 10—System-Disabled Reporting Connection

Number . . . . . . . . . . . . . . 144


Key 11—System-Disabled Call-Back Connection

Number . . . . . . . . . . . . . . 144


Key 12—Service Provider Connection Number 145


Error Messages . . . . . . . . . . . . 145

Retrieve XML Service Information (QSCRXMLI)

API . . . . . . . . . . . . . . . . . 145



DEST0100 Format . . . . . . . . . . . 147


DEST0200 Format . . . . . . . . . . . 148

SIRV0100 Format . . . . . . . . . . . 148


SSIF0100 Service Selection Information from a

Nonprogram Message Queue Format . . . . 148


SSIF0200 Service Selection Information from a

Program Message Queue of a Job Format . . . 149


SSIF0300 Service Selection Information from the

History Log . . . . . . . . . . . . . 149


Usage Notes . . . . . . . . . . . . . 153

Error Messages . . . . . . . . . . . . 153

Send Service Request (QPDETSND) API . . . . 155



SNDR0100 - Refresh Policy File Request . . . 156

SNDR0200 - Start a Function Request . . . . 156

SNDR0300 - Stop a Function Request . . . . 156

SNDR0400 - Service Event Request . . . . . 156

SNDR0500 - Change Logging Levels Request 157

SNDR0600 - Handle Changed System Value

Request . . . . . . . . . . . . . . 157


Error Messages . . . . . . . . . . . . 159

Set User Policy (QPDETPOL) API . . . . . . 159



POLS0100 - Format for setting service interval

policy for Service Monitor cleanup . . . . . 160

POLS0200 - Format for setting the level of

problem documentation sent with a problem . . 161

POLS0300 - Format for setting maximum PTF

order size and downloading time . . . . . . 161

POLS0400 - Format for setting the period of

time for problem processing . . . . . . . 161

POLS0500 - Format for setting preferred action

when reporting a problem . . . . . . . . 161


Error Messages . . . . . . . . . . . . 163

Exit Programs . . . . . . . . . . . . . 163

Watch for Trace Event Exit Program . . . . . . 163




Contents v


Concepts . . . . . . . . . . . . . . . 166

Key Groups for Problem Log APIs . . . . . . 167

Key Use for Problem Log APIs . . . . . . 167

Key Utilization Matrix . . . . . . . . . 167

Key Group 0000-General Problem Log Entries . . 168

Key 1—Problem Log ID . . . . . . . . . 169

Key 2—Problem Type . . . . . . . . . 169

Key 3—Problem Status . . . . . . . . . 169

Key 4—User Assigned . . . . . . . . . 170

Key 5—Problem Origin System . . . . . . 170

Key 6—Operational Data . . . . . . . . 171

Key 7—Filter Control . . . . . . . . . . 172

Key 8—Answer Codes . . . . . . . . . 172

Key Group 1000—Problem Description Entries . . 173

Key 1001—Problem Severity . . . . . . . 173

Key 1002—Problem Description Message . . . 173

Key 1003—Problem Creation Data . . . . . 174

Key 1004—Reporting Device . . . . . . . 174

Key 1005—Failing Resource . . . . . . . 175

Key 1006—Reporting Code . . . . . . . . 176

Key 1007—Problem Analysis Data . . . . . 176

Key 1008—Fix Verification Status . . . . . . 177

Key 1009—Fix Recovery Status . . . . . . 177

Key 1010—Symptom String . . . . . . . 177

Key 1011—PTF Media Selection . . . . . . 178

Key 1012—Problem Category . . . . . . . 178

Key 1013—Client Information . . . . . . . 178

Key 1014—First Failure Data Capture . . . . 179

Key 1015—Query Status . . . . . . . . . 180

Key 1016—Hardware Location Information . . 180

Key Group 2000—FRU Entries . . . . . . . 180

Key 2000—Number of FRU Entries to Work

with . . . . . . . . . . . . . . . 180

Key 2001—Device FRU Type . . . . . . . 181

Key 2002—Code FRU Type . . . . . . . . 182

Key 2003—Media FRU Type . . . . . . . 183

Key 2004—User FRU Type . . . . . . . . 183

Key 2005—FRU Name . . . . . . . . . 184

Key 2006—Attached FRU . . . . . . . . 184

Key 2007—Configuration FRU . . . . . . . 185

Key 2008—General FRU . . . . . . . . . 185

Key 2009—Channel Attached FRU . . . . . 186

Key Group 3000—Text Entries . . . . . . . . 186

Key 3000—Text Entry . . . . . . . . . . 186

Key 3001—Text Entry . . . . . . . . . . 187

Key Group 4000-Supporting Data Entries . . . . 188

Key 4000—Supporting Data Entries . . . . . 188

Key 4001—Spooled File Data . . . . . . . 188

Key 4002—File Data . . . . . . . . . . 189

Key Group 5000—Contact Entries . . . . . . 189

Key 5000—Contact Entries . . . . . . . . 189

Key 5001—Contact Information . . . . . . 190

Key Group 6000—Problem History Entries . . . 191

Key 6000—History Information . . . . . . 191

Key 6001—History Information . . . . . . 192

Key Group 7000—PTF Entries . . . . . . . . 192

Key 7000—PTF Entry . . . . . . . . . . 192

Key 7001—PTF ID . . . . . . . . . . . 193

Key 7002—PTF ID . . . . . . . . . . . 194

Key Group 8000—Analyzed Error Entries . . . 194

Key Group 9000—Logical Partition ID Entries 195

Field Descriptions for Key Groups for Problem Log

APIs . . . . . . . . . . . . . . . . 195

QTRC Trace Definitions . . . . . . . . . . 211

A . . . . . . . . . . . . . . . . . 211

C . . . . . . . . . . . . . . . . . 211

E . . . . . . . . . . . . . . . . . 212

F . . . . . . . . . . . . . . . . . 212

I . . . . . . . . . . . . . . . . . . 212

L . . . . . . . . . . . . . . . . . 212

S . . . . . . . . . . . . . . . . . 213

T . . . . . . . . . . . . . . . . . 213

V . . . . . . . . . . . . . . . . . 213

QTRC Trace Levels . . . . . . . . . . . 214

Choosing the Coded Trace Level . . . . . . 214

QTRC Trace Data Collected . . . . . . . . . 214

Trace Data Collected . . . . . . . . . . 214

Trace Data Automatically Collected . . . . . 215

Print Trace (PRTTRC) Output . . . . . . . 215

QTRC Trace Collecting a Component Trace . . . 216

Start Trace (STRTRC) . . . . . . . . . . 216

End Trace (ENDTRC) . . . . . . . . . . 216

Print Trace (PRTTRC) . . . . . . . . . . 217

Delete Trace (DLTTRC) . . . . . . . . . 217

QTRC Trace Tips . . . . . . . . . . . . 217

Performance . . . . . . . . . . . . . 217

Character Data Processing . . . . . . . . 218

Header Files for UNIX-Type Functions . . . . . 218

Errno Values for UNIX-Type Functions . . . . . 221

Code license and disclaimer information . . . . 229

Appendix. Notices . . . . . . . . . 231

Programming interface information . . . . . . 232

Trademarks . . . . . . . . . . . . . . 233

Terms and conditions . . . . . . . . . . . 234

vi System i: Programming Problem Management APIs

Problem Management APIs

The problem management APIs offer you the ability to write problem management solutions, improve

serviceability, and manage your own applications. The problem management APIs deal directly with how

the system handles problems today. The problem log provides most of the operations necessary for

problem management in a network environment.

The problem management APIs are organized into the following groups:

v “Monitoring APIs”

v

“Problem Determination APIs” on page 14

v “Problem Logging APIs” on page 32

v

“QTRC Trace APIs” on page 72

v “Service APIs” on page 103

Filtering

In the problem management APIs, a filter categorizes problem log entries into groups and performs

operations on them accordingly. The problem log applies the currently active filter to a problem log entry

whenever a problem entry is created, changed, or deleted using system-provided interfaces.

The operations supported allow you to send application notification to a user data queue and assign the

problem to a user. Your application can receive these notifications from the data queue using existing

APIs. See also Data Queue APIs.

Working with a Problem

Problem analysis is the process of finding the cause of a problem and identifying why the system is not

working. Often, this process identifies equipment or data communications functions as the source of the

problem. The “Work with Problem (QPDWRKPB) API” on page 69 allows you to perform problem

analysis on local machine-detected problems in the problem log. The Work with Problem (QPDWRKPB)

API prepares the problem in the problem log for reporting; it does not report the problem automatically.

Key Groups

See “Key Groups for Problem Log APIs” on page 167 for information about keys for problem log APIs.

Top | APIs by category

APIs

These are the APIs for this category.

Monitoring APIs

The monitoring APIs include:

v “End Watch (QSCEWCH) API” on page 2 (QSCEWCH) ends a watch session that was started by a

STRWCH (Start Watch) command or by the Start Watch (QSCSWCH) API.

v “Start Watch (QSCSWCH) API” on page 3 (QSCSWCH) starts the watch for event function, which

notifies the user by calling a user specified program when the specified event (a message or LIC log)

occurs.

© Copyright IBM Corp. 1998, 2008 1

obj2.htm

#TOP_OF_PAGE

aplist.htm

v “Start Watch Command or API Exit Program (QPDETWCH) API” on page 13 (QPDETWCH) can be

used as the exit program for the Start Watch (STRWCH) Command or Start Watch (QSCSWCH) API.

The monitoring exit programs include:

v Watch for Event is started by the STRWCH command or the Start Watch (QSCSWCH) API, and has the

capability to notify the user by calling a user exit program when the specified event occurs.

v “Watch for Trace Event Exit Program” on page 163 is called while using commands to watch for

specific events, such as messages being sent to a particular queue.

See Registered Filter APIs for related information.

“Problem Management APIs,” on page 1 | APIs by category

End Watch (QSCEWCH) API

Required Parameter Group:

1 Session ID Input Char(10)

2 Error Code I/O Char(*)

Default Public Authority: *EXCLUDE Threadsafe: Yes

The End Watch (QSCEWCH) API ends a watch session that was started by a STRWCH (Start Watch)

command or by the Start Watch (QSCSWCH) API.

Watch sessions started by trace commands

(STRTRC, TRCINT, TRCCNN, STRCMNTRC, TRCTCPAPP) will be ended but the associated trace will

remain active.

Note: A watch session can be ended from the same job that issued the start function or from a different

job.

Authorities and Locks

Authority to use the API

To use this API, you must have service (*SERVICE) special authority or must be authorized to the

Service watch function of the i5/OS®

operating system through System i™ Navigator’s Application

Administration support. The Change Function Usage (CHGFCNUSG) command, with a function

ID of QIBM_SERVICE_WATCH, can also be used to change the list of users that are allowed to

start and end watch operations.

Authority to watch session

If ending a watch session that is watching for a message within a job log, the issuer of the API

must be running under a user profile which is the same as the job user identity of the job being

watched, or the issuer of the API must be running under a user profile which has job control

(*JOBCTL) special authority. Job control (*JOBCTL) special authority is also required when ending

a session where jobs with a generic user name are being watched.

If you end a watch session that was started with *ALL for the watch job name or with a generic

user name, you must have *ALLOBJ special authority or must be authorized to the Watch Any

Job function of the i5/OS operating system through System i Navigator’s Application


ID of QIBM_WATCH_ANY_JOB, can also be used to change the list of users that are allowed to


2 System i: Programming Problem Management APIs

xwchevnt.htm

netmg5.htm

aplist.htm

Required Parameter Group

Session ID

INPUT; CHAR(10)

The session identifier for the watch to be ended. This name must match the session identifier of a

watch that had been previously started and is still active. You can use this special value for this

parameter:

*PRV The watch session most recently started by the same user who is running this API will be ended. For

example, if the job running the API is running under user profile BOB, the last watch session started

under user profile BOB is ended.

Error code

I/O; CHAR(*)

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

parameter.

Error Messages

The following messages may be sent from this function:

Message ID Error Message Text

CPF24B4 Severe error while addressing parameter list.

CPF3CF1 Error code parameter not valid.

CPF39E1 Watch session ID &1 not found.

CPF39E2 There is not any active watch session for current user profile.

CPF39E6 The user does not have the required authority.

CPF39E8 Not enough authority to watch operations.

CPF39E9 *JOBCTL special authority required.

CPF9872 Program or service program &1 in library &2 ended. Reason code &3.

API introduced: V5R4

Top | “Problem Management APIs,” on page 1 | APIs by category

Start Watch (QSCSWCH) API



2 Started session ID Output Char(10)

3 Watch program Input Char(20)

4 Watch for message Input Char(*)

5 Watch for LIC log entry Input Char(*)


Optional Parameter Group 1:

Problem Management APIs 3

#TOP_OF_PAGE

aplist.htm

7 Watch session attributes Input Char(*)


8 Watch for PAL entry Input Char(*)


The Start Watch (QSCSWCH) API starts the watch for event function, which notifies the user by calling a

user specified program when the specified event (a message, a LIC log

or a PAL

) occurs.

PAL

stands for Product Activity Log which shows errors that have occurred (such as in disk and tape units,

communications, and work stations).

Up to 10000 watch sessions can be active at a time. The watch session continues until ended with the End

Watch (QSCEWCH) API or with the End Watch (ENDWCH) command.

Note: A watch session can be ended from the same job or a different job.




Service watch function of the i5/OS®



ID of QIBM_SERVICE_WATCH, can also be used to change the list of users that are allowed to


Authority to watch program

You must have operational (*OBJOPR) and execute (*EXECUTE) authorities to the watch program

to be called, and execute (*EXECUTE) authority to the library where the program is located.

Authority to message queue

You must have use (*USE) authority to the message queue specified in watched message queue

name field, and use (*USE) authority to the library where the message queue is located.

Authority to watched job

When a message is being watched within a job, the issuer of the API must be running under a

user profile which is the same as the job user identity of the job being watched, or the issuer of

the API must be running under a user profile which has job control (*JOBCTL) special authority.

Job control (*JOBCTL) special authority is also required if a generic user name is specified in the

watched job user name field.

If you specify *ALL for the watched job name, or a generic user name, you must have all object

(*ALLOBJ) special authority or must be authorized to the Watch Any Job function of the i5/OS

operating system through System i Navigator’s Application Administration support. The Change

Function Usage (CHGFCNUSG) command, with a function ID of QIBM_WATCH_ANY_JOB, can

also be used to change the list of users that are allowed to start and end watch operations.


Session ID

INPUT; CHAR(10)


The session identifier for this watch. This watch session identifier must be unique across all active

watch sessions on the system. You cannot specify a session identifier that starts with ″QSC″. You

can use this special value for this parameter:

*GEN The system will generate a unique session identifier for this watch that will be returned as output

in Started session ID parameter.

Started session ID

OUTPUT; CHAR(10)

The identifier of the watch session just started.

Watch program

INPUT; CHAR(20)

The program to be called to notify that a specified watch event occurred. The watch program will

be called after a match of a message identifier and any associated comparison data specified for

the watch for message parameter, or a match of a Licensed Internal Code (LIC) log entry and any

associated comparison data specified for the watch for LIC log entry parameter occurs,

or a

match of a Product Activity Log (PAL) entry and any associated comparison data specified for

the watch for PAL entry parameter occurs. The watch program will also be called at the times

specified in the call watch program options field in watch session attributes parameter.

The exit program will be called once for each message id and LIC log entry and

PAL entry

specified on this API. That is, if a message is watched on a message queue and in a job log, and

the message is sent to both locations, the exit program will be called twice.

The information must be in the following format:

Watch program name

CHAR(10)

The name of the user-written program to call.

Watch program library

CHAR(10)

The library where the user-written program is located. You can use one of these special

values for this field:

*LIBL All libraries in the job’s library list are searched until the first match is found.

*CURLIB The current library for the job is used to locate the program. If no library is specified as the

current library for the job, the QGPL library is used.

Watch for message

INPUT; CHAR(*)

The message identifiers which are to be watched for and where to watch for them. The

information must be in the following format:

Number of messages being watched

BINARY(4)

The total number of all of the messages to watch for within this session. Up to 100

messages might be watched at the same time by a single session.

Message information

Each message being watched contains a message id, where to watch for the message

(message queue or job log) and it may specify a message comparison data. Refer to

“Format for message information” on page 7 for the format of this field.


Watch for LIC log entry

INPUT; CHAR(*)

The licensed internal code (LIC) log entry identifiers which are to be watched for. The watched

for condition will be met if a LIC log entry is added that matches the specified major and minor

codes and any comparison data specified. The information must be in the following format:

Number of LIC logs being watchedBINARY(4)

The total number of all of the LIC logs to watch for. Up to five LIC logs can be specified.

LIC log information

Each LIC log entry contains a major and a minor code and it may specify a LIC log

comparison data. Refer to “Format for LIC log information” on page 7 for the format of

this field.

Error code

I/O; CHAR(*)


parameter.

Optional Parameter Group 1

Watch session attributes

INPUT; CHAR(10)

The properties of the watch session to run. The information must be in the following format. For

a detailed description of each field, see Field Descriptions.

Offset

Type Field Dec Hex

0 0 BINARY(4) Length of attributes information

4 4 BINARY(4) Run priority

8 8 BINARY(4) Offset to call watch program options

12 C BINARY(4) Number of call watch program options

* * Array of CHAR(10) Call watch program options


Watch for PAL entry

INPUT; CHAR(*)

The Product Activity Log (PAL) entries which are to be watched for. The watched for condition

will be met if a PAL entry is added that matches the specified system reference code and any

comparison data specified. The information must be in the following format:

Number of PALs being watched

BINARY(4)

The total number of all of the PALs to watch for. Up to five PALs can be specified.

PAL information

Each PAL entry contains a system reference code and it may specify a comparison data.

Refer to Format for PAL information for the format of this field.


#HDRERRCOD

#HDRERRCOD

#FIELDS

Format for message information

The following table shows the format for the messages to be watched for. For a detailed description of

each field, see “Field Descriptions” on page 8.

Offset

Type Field Dec Hex

0 0 BINARY(4) Length of message information

4 4 CHAR(7) Message id

11 B CHAR(1) Reserved

12 C CHAR(10) Watched message queue name

22 16 CHAR(10) Watched message queue library

32 20 CHAR(10) Watched job name

42 2A CHAR(10) Watched job user name

52 34 CHAR(6) Watched job number

58 3A CHAR(6) Reserved

64 40 BINARY(4) Offset to message comparison data

68 44 BINARY(4) Length of message comparison data

72 48 CHAR(10) Compare against

82 52 CHAR(*) Message comparison data

Format for LIC log information

The following table shows the format for the LIC logs to be watched for. For a detailed description of

each field, see “Field Descriptions” on page 8.

Offset

Type Field Dec Hex

0 0 BINARY(4) Length of LIC log information

4 4 CHAR(4) LIC log major code

8 8 CHAR(4) LIC log minor code

12 C BINARY(4) Offset to LIC log comparison data

16 10 BINARY(4) Length of LIC log comparison data

20 14 CHAR(10) LIC log compare against

* * CHAR(*) LIC log comparison data

Format for PAL information

The following table shows the format for the PALs to be watched for. For a detailed description of each

field, see “Field Descriptions” on page 8.


Offset

Type Field Dec Hex

0 0 BINARY(4) Length of PAL information

4 4 CHAR(8) System reference code

12 C BINARY(4) Offset to PAL comparison data

16 10 BINARY(4) Length of PAL comparison data

20 14 CHAR(10) PAL compare against

* * CHAR(*) PAL comparison data

Field Descriptions

Call watch program options. The times at which the watch program will be called. The program will

always be called when the watched for event occurs. You can specify additional times for the program to

be called:

*STRWCH The watch program will also be called before starting watching for any event.

*ENDWCH The watch program will also be called when the watch session is ending. Possible reasons might

be:

v End Watch (ENDWCH) command or End Watch (QSCEWCH) API was issued.

v One or more of the watch for event jobs ended abnormally or ended by user action

Note: A watch session might end because an error was detected on the watch exit program. In this

case, the watch program will not be called at *ENDWCH time.

Compare against. The part of the message the data specified in message comparison data field is to be

compared against. You must specify blanks if zero was specified for the length of message comparison

data field. You can specify the following special values for this field:

*MSGDTA The message comparison data will be compared against the message replacement data.

*FROMPGM The message comparison data will be compared against the name of the program sending the

message, or the name of the ILE program that contains the procedure sending the message.

*TOPGM The message comparison data will be compared against the name of the program the message was

sent to, or the name of the ILE program that contains the procedure the message was sent to.

Length of attributes information. The length of the fixed portion of the structure containing the watch

session attributes information. The maximum length is 16.

Length of LIC log comparison data. The length of the text specified in LIC log comparison data field.

Valid values are 0 through 72.

Length of LIC log information. The length of the structure containing the information of the LIC log to

watch for.

Length of message comparison data. The length of the text specified in message comparison data field.

Valid values are 0 through 72.

Length of message information. The length of the structure containing the information of the message to

watch for.


Length of PAL comparison data. The length of the text specified in PAL comparison data field. Valid

values are 0 through 10.

Length of PAL information. The length of the structure containing the information of the PAL to watch

for.

LIC log compare against. The part of the LIC log the data specified in LIC log comparison data field is to

be compared against. You must specify hexadecimal zeros (x’00’) if zero was specified for the length of

LIC log comparison data field. If not specified, the default value is *ALL. You can specify the following

special values for this field:

*ALL The LIC log comparison data will be compared against all the fields described below.

*TDENBR The LIC log comparison data will be compared against the number of the task dispatching

element (TDE) which requested the LIC log entry.

*TASKNAME The LIC log comparison data will be compared against the name of the task which requested the

LIC log entry. Task name is blank (hex 40s) if the LIC log entry is not requested by a task.

*SVRTYPE The LIC log comparison data will be compared against the type of server that requested the LIC

log entry. Server type is blank (hex 40s) if the LIC log entry is not requested by a server.

*JOBNAME The LIC log comparison data will be compared against the name of the job which requested the

LIC log entry. LIC job name is blank (hex 40s) if the LIC log entry is not requested by a job.

*JOBUSR The LIC log comparison data will be compared against the user name of the job which requested

the LIC log entry. LIC user name is blank (hex 40s) if the LIC log entry is not requested by a job.

*JOBNBR The LIC log comparison data will be compared against 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 is not requested by a job.

*THDID The LIC log comparison data will be compared against the thread which requested the LIC log

entry. Thread identifier is binary zeros if the LIC log entry is not requested by a thread.

*EXCPID The LIC log comparison data will be compared against the exception that caused the LIC 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 is not requested as a result of an exception.

*MODNAME The LIC log comparison data will be compared against the LIC module name which requested the

LIC log entry. If the module name is greater than 64 characters, the LIC module name is truncated

to 64 characters.

*MODRUNAME The LIC log comparison data will be compared against the LIC module replacement unit name.

LIC module RU name is always in upper case EBCDIC.

*MODEPNAME The LIC log comparison data will be compared against 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.

*MODOFFSET The LIC log comparison data will be compared against the byte offset into the LIC module text

which requested the LIC log entry.

*MODTSP The LIC log comparison data will be compared against the timestamp of when the LIC module

was compiled. The format for this field is the system time-stamp format.

LIC log comparison data. The comparison data to be used if a log entry matching the specified major

and minor codes is added to the licensed internal code (LIC) log. If this text is found in the LIC log entry

data field

specified by the LIC log compare against field,

the watched for condition is true. This text

is case sensitive.

If *ALL is specified in the LIC log compare against field,

the LIC log fields which

will be compared are TDE number, task name, server type, job name, user ID, job number, thread ID,

exception ID, LIC module compile binary timestamp, LIC module offset, LIC module RU name, LIC

module name, LIC module entry point name. The comparison data cannot be used to match across two

fields, and can match an entire field or a substring of any field. When watching for an exception ID, all

four hexadecimal digits of the exception ID must be specified. Also, the prefix MCH may be specified if

you want to compare only against the exception ID field and avoid possible substring matches with the

other fields.


LIC log major code. The LIC log major code to be watched for. You can specify either a hexadecimal

digit or a question mark for each character in the four-digit code. A question mark is a wildcard character

that will match any digit in that position. Up to three wildcard characters can be specified. You can

specify the following special value for this field:

*ALL Any LIC log entry major code will be considered to be a match. If *ALL is specified for the major code,

you cannot specify *ALL for the LIC log entry minor code.

LIC log minor code. The LIC log minor code to be watched for. You can specify either a hexadecimal

digit or a question mark for each character in the four-digit code. A question mark is a wildcard character

that will match any digit in that position. Up to three wildcard characters can be specified. You can

specify the following special value for this field:

*ALL Any LIC log entry minor code will be considered to be a match. If *ALL is specified for the minor code,

you cannot specify *ALL for the LIC log entry major code.

Message comparison data. The comparison data to be used if a message matching the specified message

ID is added to the specified message queue or log. If the message data, the ″From program″ or the ″To

program″ includes the specified text, the watched for condition is true. This text is case sensitive.

Message id. The 7-character message identifier to be watched for.

Number of call watch program options. The number of values specified in the call watch program

options field array. If zero is specified the watch program will be called only when the specified event

occurs.

Offset to LIC log comparison data. The offset to the field that holds the LIC log comparison data.

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

Offset to PAL comparison data. The offset to the field that holds the PAL comparison data.

Offset to call watch program options. The offset to the array that defines when the watch program is to

be called. If this value is 0 then the watch program will be called only when the specified event occurs.

PAL compare against. The part of the PAL the data specified in PAL comparison data field is to be

compared against. You must specify blanks if zero was specified for the length of PAL comparison data

field. You can specify the following special values for this field:

*RSCNAME The PAL comparison data will be compared against the resource name.

*RSCTYPE The message comparison data will be compared against the resource type.

*RSCMODEL The PAL comparison data will be compared against the resource model.

PAL comparison data. The comparison data to be used if a PAL entry matching the specified system

reference code was created. If the data specified by PAL compare against field matches the specified text,

the watched for condition is true. This text is case sensitive. You can specify question mark (?) and

asterisk (*) wildcard characters in the text string. A question mark is a single-character wildcard character

and will match any character in the same position. For example, ’??123’ will match any value that is five

characters long and ends with ’123’. Multiple question mark wildcard characters can be specified for the

comparison data value. An asterisk is a multiple-character wildcard character. You can specify a single

asterisk wildcard character at the end of the comparison data value. For example, ’ABC*’ will match any

value that begins with the letters ’ABC’.


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

Run priority. The priority for the job where the watch session work will be run. The default job run

priority of 25 will be used if the watch session attributes parameter is not specified. The possible values

are:

0 The default job run priority of 25 will be used.

-1 The run priority of the current job will be used.

priority The range of values is 1 (highest priority) to 99 (lowest priority).

See the Work management topic collection for more information about the run priority.

System reference code. The system reference code to be watched for. You can specify either a

hexadecimal digit or a question mark for each character in the eight-digit code. A question mark is a

wildcard character that will match any digit in that position. Up to seven wildcard characters can be

specified. You can also specify a generic name that is a character string of one or more characters

followed by an asterisk (*); for example, ABC*. The asterisk substitutes for any valid characters. A generic

name specifies all PALs with system reference codes that begin with the generic prefix.

You can specify the following special value for this field:

*ALL Any PAL system reference code will be considered to be a match.

Watched job name. The name of the job to be watched. You must specify blanks if something different

from *JOBLOG is specified for watched message queue name field. You can specify the following special

values for this field:

generic-name The generic name of the job to be watched. A generic name is a character string of one or more

characters followed by an asterisk (*); for example, ABC*. The asterisk substitutes for any valid

characters. A generic job name specifies all jobs with job names that begin with the generic prefix.

* Only the job log of the job that issued this API is watched.

*ALL All jobs with the specified job user name are watched. *ALL for the job name is considered to be a

generic job specification because it will watch all jobs that meet the job user name qualifier that

you specified.

Watched job number. The job number (000001-999999) to further qualify the job name and user name.

You must specify blanks if a generic job name or a generic user name qualifier is specified, or if

something different from *JOBLOG is specified for watched message queue name field. You can specify

the following special value for this field:

*ALL All jobs with the specified job name and user name are watched.

Watched job user name. The user name of the job to be watched. You must specify blanks if ’*’ is

specified for the watched job name field or something different from *JOBLOG is specified for watched

message queue name field. You can specify the following special value for this field:

generic-name The generic name of the user name of the job to be watched. A generic name is a character string

of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk substitutes

for any valid characters. A generic user name specifies all jobs with the specified job name and

with user names that begin with the generic prefix.

*ALL All jobs with the specified job name are watched. *ALL for the job user name is considered to be a

generic job specification because it will watch all jobs that meet the job name qualifier that you

specified.


Watched message queue library. The name of the library where the message queue is located. This field

is ignored if *SYSOPR, *JOBLOG or *HSTLOG was specified in the message queue name. You can specify

the following special value for this field:

*LIBL All libraries in the job’s library list are searched until the first match is found.

Watched message queue name. The name of the message queue to watch. You can specify the following

special values for this field:

*SYSOPR Watch messages added to the system operator message queue (QSYSOPR message queue in

library QSYS).

*JOBLOG Watch messages added to the job logs of the jobs specified for the watched job field.

*HSTLOG Watch messages added to the history log (QHST message queue in library QSYS).

Error Messages



CPF13A3 Value &1 for run priority not valid.


CPF2401 Not authorized to library &1.

CPF2403 Message queue &1 in &2 not found.

CPF2408 Not authorized to message queue &1.


CPF3C1D Length specified in parameter &1 not valid.

CPF3C20 Error found by program &1.

CPF3C3A Value for parameter &2 for API &1 not valid.

CPF39D0 Watch for event function cannot start.

CPF39D1 Limit exceeded for jobs watching for trace events.

CPF39EA Value specified for watched job user name filed is not valid.

CPF39EB Watched job name, watched job user name or watched job number field not valid.

CPF39E3 Session ID &1 already exists.

CPF39E4 Specify Watch for message, LIC log entry or PAL entry.

CPF39E5 No active jobs found, watch session not started.

CPF39E6 The user does not have the required authority.

CPF39E7 Invalid session identifier.

CPF39E8 Not enough authority to watch operations.

CPF39E9 *JOBCTL special authority required.

CPF3958 Not authorized to use program &1 in library &2.

CPF9811 Program &1 in library &2 not found.





#TOP_OF_PAGE

aplist.htm

Start Watch Command or API Exit Program (QPDETWCH) API


1 Watch option setting Input Char(10)


3 Error detected Output Char(10)

4 Event data Input Char(*)

QSYSINC Member Name:

QPDETWCH

The Start Watch Command or API Exit Program (QPDETWCH) API can be used as the exit program for

the Start Watch (STRWCH) Command or Start Watch (QSCSWCH) API. See the online help for more

information about the STRWCH command, or refer to the “Start Watch (QSCSWCH) API” on page 3.

This program takes the information supplied by the Start Watch Command or API, generates an XML

service request, and places that service request on the Service Monitor queue.


None.


Watch option setting

INPUT; CHAR(10)

The reason indicating why the exit program was called.

The possible values are:

*MSGID A match on a message id and any associated comparison data specified on watch for message

parameter occurred.

*LICLOG A match on a LIC log and any associated comparison data specified on the watch for LIC log

entry parameter occurred.

*PAL A match on a Product Activity Log (PAL) and any associated comparison data specified on the

watch for PAL entry parameter occurred.

Session ID

INPUT; CHAR(10)

The name of the session that is calling the exit program.

Length of receiver variable

INPUT; BINARY(4)

The length of the receiver variable described in Format of data returned. If the length is larger

than the size of the receiver variable, the results may not be predictable. The minimum length is 8

bytes.

Error detected

OUTPUT; CHAR(10)

Indicates if an error in the exit program was found.


*ERROR Error detected by watch exit program. The watch session that was passed in Session ID parameter

will be ended. If the watch session to be ended originally specified multiple message ids, LIC log

entries,

or PAL entries

, all of them will no longer be watched.


<blanks> No error detected by watch exit program.

Note: Any value other than “ERROR” or <blanks> will be considered an error and the watch

session that was passed in Session ID parameter will be ended. If the watch session to be ended

originally specified multiple message ids, LIC log entries,

or PAL entries

, all of them will no

longer be watched.

Event data

INPUT; CHAR(*)

The format of the watch information depends on the Watch option setting causing the exit

program to be called.

Information about the format of the event data can be found in Watch for Event Exit Program.



Problem Determination APIs

The problem determination APIs are:

v “Qp0zDump()—Dump Formatted Storage Trace Data” on page 15 (Dump Formatted Storage Trace

Data) dumps the user storage specified by area to the user trace.

v “Qp0zDumpStack()—Dump Formatted Stack Trace Data” on page 18 (Dump Formatted Stack Trace

Data) dumps a formatted representation of the call stack of the calling thread to the user trace.

v “Qp0zDumpTargetStack()—Dump Formatted Stack Trace Data of the Target Thread” on page 22

(Dump Formatted Stack Trace Data of the Target Thread) dumps a formatted representation of the call

stack of the target thread to the user trace.

v “Qp0zLprintf()—Print Formatted Job Log Data” on page 25 (Print Formatted Job Log Data) prints user

data specified by format-string as an information message type to the job log.

v “Qp0zUprintf()—Print Formatted User Trace Data” on page 28 (Print Formatted User Trace Data) prints

user data specified by the format-string parameter to the user trace.

v

“Join Trace (QSCJOINT) API” on page 30 (Join Trace) sets and clears the trace characteristics of the

current job.

Note: Some of these functions unconditionally write the specified application data. The use of these

functions should be limited to unexpected failure, exception or other error conditions. The preferred

method for writing application trace data is through the use of the “QTRC Trace APIs” on page 72.

Note: These functions use header (include) files from the library QSYSINC, which is optionally

installable. Make sure QSYSINC is installed on your system before using any of the functions. See

“Header Files for UNIX-Type Functions” on page 218 for the file and member name of each header file.

The problem determination APIs are intended to be used as an aid in debugging exception or error

conditions in application programs. These functions should not be used in performance critical code.

These functions can be used during application development, as well as after the application is made

available, as debug mechanisms. For example, a compile option could be used to activate the problem

determination functions during application development. When the application is ready to be made

available, recompile to deactivate the functions.


xwchevnt.htm

#TOP_OF_PAGE

aplist.htm

Some of the problem determination functions dump or print to the user trace. The user trace is a

permanent user space object named QP0Z<jobnumber> in the QUSRSYS library. The user trace is created

the first time any thread in a job writes user trace output. The following CL commands can be used to

manipulate the user trace properties and objects:

v Change User Trace (CHGUSRTRC) can be used to change the characteristics of the user trace.

v Dump User Trace (DMPUSRTRC) can be used to dump user trace records to a file or to standard

output.

v Delete User Trace (DLTUSRTRC) can be used to delete the user trace objects.

For those problem determination functions that use the user trace, the following should be considered:

v The functions require no authority to the user trace object. See CL commands CHGUSRTRC,

DMPUSRTRC, and DLTUSRTRC for the authority required to administer, display, or modify tracing

information using the CL commands.

v No locks are held on the user trace between calls to the tracing functions. The user trace can be deleted

while in use. The next function that produces user trace output will create the user trace again.

v If another job on the system has the same job number as an existing user trace, the existing user trace

data is cleared, and the data from the new job replaces it.


Qp0zDump()—Dump Formatted Storage Trace Data

Syntax #include <qp0ztrc.h>

void Qp0zDump(const char *label,

void *area,

int len);

Service Program Name: QP0ZCPA Default Public Authority: *USE Threadsafe: Yes

The Qp0zDump() function dumps the user storage specified by area to the user trace. The user-provided

storage is formatted for viewing in hexadecimal representation for up to len number of bytes. The

formatted storage is labeled with the text string specified by label.

If any input parameters are not valid, or an incorrect or error condition is detected, the Qp0zDump()

function returns immediately and no error is indicated.

An application should not use the tracing function in performance critical code. These functions are

intended for debugging exception or error conditions. The user trace is a permanent user space object

named QP0Z<jobnumber> in the QUSRSYS library. The user trace is created the first time any thread in a

job writes trace output. See the Change User Trace (CHGUSRTRC), Dump User Trace (DMPUSRTRC) and

Delete User Trace (DLTUSRTRC) CL commands for information about manipulating the user trace

properties and objects.

Parameters

label (Input) A pointer to a string that is used to label the storage dump.

area (Input) A pointer to storage area that is to be formatted and dumped to the user trace.

len (Input) The number of bytes of storage to be formatted in the user trace.


#TOP_OF_PAGE

aplist.htm

Authorities

None.

Return Value

None.

Error Conditions

If Qp0zDump() is not successful, the function returns immediately and no error is indicated.

Usage Notes

1. No locks are held on the user trace between calls to the tracing functions. The user trace can be

deleted while in use. The next function that produces trace output will create the user trace again.

2. If another job on the system has the same job number as an existing user trace, the existing trace data

is cleared, and the trace data from the new job replaces it.

3. As the format of the user trace records can change, only the following CL commands can be used to



v Dump User Trace (DMPUSRTRC) can be used to dump trace records to a file or to standard output.


Related Information

v “Qp0zDumpStack()—Dump Formatted Stack Trace Data” on page 18—Dump Formatted Stack Trace

Data

v “Qp0zDumpTargetStack()—Dump Formatted Stack Trace Data of the Target Thread” on page

22—Dump Formatted Stack Trace Data of the Target Thread

v “Qp0zLprintf()—Print Formatted Job Log Data” on page 25—Print Formatted Job Log Data

v “Qp0zUprintf()—Print Formatted User Trace Data” on page 28—Print Formatted User Trace Data

Example

The following example uses Qp0zDump() and Qp0zUprintf() functions to produce trace output.

Note: By using the code examples, you agree to the terms of the “Code license and disclaimer

information” on page 229.

#define _MULTI_THREADED

#include <pthread.h>

#include <stdio.h>

#include <stdlib.h>

#include <unistd.h>

#include <qp0ztrc.h>

#define THREADDATAMAX 128

void *theThread(void *parm)

{

char *myData = parm;

printf("Entered the %s thread\n", myData);

Qp0zUprintf("Tracing in the %s thread\n", myData);

Qp0zDump("The Data", myData, THREADDATAMAX);

free(myData);

return NULL;

}


int main(int argc, char **argv)

{

pthread_t thread, thread2;

int rc=0;

char *threadData;

printf("Enter Testcase - %s\n", argv[0]);

Qp0zUprintf("Tracing Testcase Entry\n");

printf("Create two threads\n");

Qp0zUprintf("Tracing creation of two threads\n");

threadData = (char *)malloc(THREADDATAMAX);

memset(threadData, ’Z’, THREADDATAMAX);

sprintf(threadData, "50%% Cotton, 50%% Polyester");

rc = pthread_create(&thread, NULL, theThread, threadData);

if (rc) {

printf("Failed to create a %s thread\n", threadData);

exit(EXIT_FAILURE);

}


memset(threadData, ’Q’, THREADDATAMAX);

sprintf(threadData, "Lacquered Camel Hair");

rc = pthread_create(&thread2, NULL, theThread, threadData);

if (rc) {


exit(EXIT_FAILURE);

}

printf("Wait for threads to complete\n");

rc = pthread_join(thread, NULL);

if (rc) { printf("Failed pthread_join() 1\n"); exit(EXIT_FAILURE); }

rc = pthread_join(thread2, NULL);


printf("Testcase complete\n");

Qp0zUprintf("Tracing completion of the testcase rc=%d\n", rc);

return 0;

}

Trace Output:

This trace output was generated after the test case was run by using the CL command DMPUSRTRC

JOB(100464/USER/TPZDUMP0) OUTPUT(*STDOUT). The above example program ran as job

100464/USER/TPZDUMP0.

Note the following in the trace output:

1. Each trace record is indented by several spaces to aid in readability. Trace records from different

threads have different indentation levels.

2. Each trace record is identified by the hexadecimal thread ID, a colon, and a timestamp. The

timestamp can be used to aid in debugging of waiting or looping threads. For example, the third trace

record shown below (the Tracing Testcase Entry trace point) was created by thread 0x13, and occurred

0.870960 seconds after the last full date and time label. This means that the trace record was created

on 5 January 1998 at 14:08:28.870960. A full date and time label is placed between those trace points

that occur during different whole seconds.


User Trace Dump for job 100464/USER/TPZDUMP0. Size: 300K, Wrapped 0

times. --- 01/05/1998 14:08:28 ---

00000013:870960 Tracing Testcase Entry

00000013:871720 Tracing creation of two threads

00000014:879904 Tracing in the 50% Cotton, 50% Polyester thread

00000014:880256 C66E80F4DF:001F60 L:0080 The Data

00000014:880968 C66E80F4DF:001F60 F5F06C40 C396A3A3 96956B40 F5F06C40 *50% Cotton, 50% *

00000014:881680 C66E80F4DF:001F70 D79693A8 85A2A385 9900E9E9 E9E9E9E9 *Polyester.ZZZZZZ*

00000014:882392 C66E80F4DF:001F80 E9E9E9E9 E9E9E9E9 E9E9E9E9 E9E9E9E9 *ZZZZZZZZZZZZZZZZ*

00000014:883096 C66E80F4DF:001F90 E9E9E9E9 E9E9E9E9 E9E9E9E9 E9E9E9E9 *ZZZZZZZZZZZZZZZZ*

00000014:883808 C66E80F4DF:001FA0 E9E9E9E9 E9E9E9E9 E9E9E9E9 E9E9E9E9 *ZZZZZZZZZZZZZZZZ*

00000014:884512 C66E80F4DF:001FB0 E9E9E9E9 E9E9E9E9 E9E9E9E9 E9E9E9E9 *ZZZZZZZZZZZZZZZZ*

00000014:885224 C66E80F4DF:001FC0 E9E9E9E9 E9E9E9E9 E9E9E9E9 E9E9E9E9 *ZZZZZZZZZZZZZZZZ*

00000015:887872 Tracing in the Lacquered Camel Hair thread

00000015:888216 C66E80F4DF:002000 L:0080 The Data

00000015:888952 C66E80F4DF:002000 D3818398 A4859985 8440C381 94859340 *Lacquered Camel *

00000015:889680 C66E80F4DF:002010 C8818999 00D8D8D8 D8D8D8D8 D8D8D8D8 *Hair.QQQQQQQQQQQ*

00000015:890416 C66E80F4DF:002020 D8D8D8D8 D8D8D8D8 D8D8D8D8 D8D8D8D8 *QQQQQQQQQQQQQQQQ*






00000014:896168 C66E80F4DF:001FD0 E9E9E9E9 E9E9E9E9 E9E9E9E9 E9E9E9E9 *ZZZZZZZZZZZZZZZZ*

00000013:898832 Tracing completion of the testcase rc=0

Press ENTER to end terminal session.



Qp0zDumpStack()—Dump Formatted Stack Trace Data


void Qp0zDumpStack(const char *label);


The Qp0zDumpStack() function dumps a formatted representation of the call stack of the calling thread

to the user trace. The formatted call stack is labeled with the text string specified by label. The formatted

call stack shows the library, program, module, and procedure information associated with each frame on

the call stack.

The formatted dump of the current call stack shows the oldest entries first, followed by newer entries.

The following example is a call stack dump if the Qp0zDumpStack() function is used to dump the stack

of the current thread. The label Thread dumping my own stack was inserted by the application program

using the label parameter.

The thread start routine in this example is threadfunc() in program or service program ATEST5 that

resides in library QP0WTEST. The threadfunc() function (at statement 2) has called the function foo().

The function foo() (at statement 1), in turn has called bar(). The function bar() (at statement 1), has

dumped the current call stack due to some application-specific error condition.


#TOP_OF_PAGE

aplist.htm

Thread dumping my own stack

Library / Program Module Stmt Procedure

QSYS / QLESPI QLECRTTH 7 : LE_Create_Thread2

QSYS / QP0WPTHR QP0WPTHR 974 : pthread_create_part2

QP0WTEST / ATEST5 ATEST5 2 : threadfunc

QP0WTEST / ATEST5 ATEST5 1 : foo

QP0WTEST / ATEST5 ATEST5 1 : bar

QSYS / QP0ZCPA QP0ZUDBG 5 : Qp0zDumpStack

QSYS / QP0ZSCPA QP0ZSCPA 199 : Qp0zSUDumpStack

QSYS / QP0ZSCPA QP0ZSCPA 210 : Qp0zSUDumpTargetStack







Parameters

label (Input) A pointer to a string that is used to label the stack dump.

Authorities

None.

Return Value

None.

Error Conditions

If Qp0zDumpStack() is not successful, the function returns immediately and no error is indicated.

Usage Notes





3. If the calling thread has more than 128 call stack entries, Qp0zDumpStack() returns after dumping

the first 128 entries of the call stack.






Related Information

v “Qp0zDump()—Dump Formatted Storage Trace Data” on page 15—Dump Formatted Storage Trace

Data




v “Qp0zUprintf()—Print Formatted User Trace Data” on page 28)—Print Formatted User Trace Data


Example

The following example uses Qp0zDumpStack() and Qp0zUprintf() functions to produce trace output.





#include <stdio.h>

#include <stdlib.h>

#include <unistd.h>



void foo(char *string);

void bar(char *string);


{


printf("Entered the %s thread\n", myData);

foo(myData);

free(myData);

return NULL;

}

void foo(char *string)

{

bar(string);

}

void bar(char *string)

{

Qp0zUprintf("function bar(): Hit an error condition!\n");

Qp0zDumpStack(string);

}


{


int rc=0;

char *threadData;

printf("Enter Testcase - %s\n", argv[0]);

Qp0zUprintf("Tracing Testcase Entry\n");






if (rc) {


exit(EXIT_FAILURE);

}




if (rc) {


exit(EXIT_FAILURE);


}






printf("Testcase complete\n");

Qp0zUprintf("Tracing completion of the testcase rc=%d\n", rc);

return 0;

}

Trace Output:


JOB(100465/USER/TPZSTK0) OUTPUT(*STDOUT). The above example program ran as job

100465/USER/TPZSTK0.






record shown below, (the Tracing Testcase Entry trace point) was created by thread 0x16, and occurred




User Trace Dump for job 100465/USER/TPZSTK0. Size: 300K, Wrapped 0 times.

--- 01/05/1998 16:32:23 ---

00000016:841456 Tracing Testcase Entry

00000016:842176 Tracing creation of two threads

00000017:850328 function bar(): Hit an error condition!

00000017:850552 Stack Dump For Current Thread

00000017:850752 Stack: 50% Cotton, 50% Polyester

00000018:853288 function bar(): Hit an error condition!


00000018:853712 Stack: Lacquered Camel Hair

00000018:888752 Stack: Library / Program Module Stmt Procedure


00000017:904848 Stack: QSYS / QLESPI QLECRTTH 774 : LE_Create_Thread2__FP12crtth_parm_t

00000017:905088 Stack: QSYS / QP0WPTHR QP0WPTHR 1004 : pthread_create_part2

00000017:905312 Stack: QP0WTEST / TPZSTK0 TPZSTK0 2 : theThread

00000017:905528 Stack: QP0WTEST / TPZSTK0 TPZSTK0 1 : foo

00000017:905744 Stack: QP0WTEST / TPZSTK0 TPZSTK0 2 : bar

00000017:905960 Stack: QSYS / QP0ZCPA QP0ZUDBG 85 : Qp0zDumpStack

00000017:906184 Stack: QSYS / QP0ZSCPA QP0ZSCPA 274 : Qp0zSUDumpStack

00000017:906408 Stack: QSYS / QP0ZSCPA QP0ZSCPA 285 : Qp0zSUDumpTargetStack

00000017:906536 Stack: Completed



00000018:908960 Stack: QP0WTEST / TPZSTK0 TPZSTK0 2 : theThread

00000018:909168 Stack: QP0WTEST / TPZSTK0 TPZSTK0 1 : foo

00000018:909384 Stack: QP0WTEST / TPZSTK0 TPZSTK0 2 : bar





00000016:912792 Tracing completion of the testcase rc=0





Qp0zDumpTargetStack()—Dump Formatted Stack Trace Data of the

Target Thread


int Qp0zDumpTargetStack(int handle,

const char *label);

Service Program Name: QP0ZCPA Default Public Authority: *USE Threadsafe: Conditional; see “Usage Notes” on page 23.

The Qp0zDumpTargetStack() function dumps a formatted representation of the call stack of the target

thread to the user trace. The target thread is specified by handle, which can be filled in using the pthread_t

structure. The formatted call stack is labeled with the text string specified by label. The formatted call

stack shows the library, program, module, and procedure information associated with each frame on the

call stack at the time the function was called.

The formatted dump of the target call stack shows the oldest entries first, followed by newer entries.

For consistent results, ensure that the target thread specified in the handle parameter is blocked or waiting

for some resource and not actively running.

If a target thread that is actively running is specified, the stack trace information may be inconsistent.







Parameters

handle (Input) A handle to the target thread.

label (Input) A pointer to a string that is used to label the stack dump.

Authorities

None.

Return Value

0 Qp0zDumpTargetStack() was successful.

value Qp0zDumpTargetStack() was not successful. The value returned is an errno indicating the failure.


#TOP_OF_PAGE

aplist.htm

Error Conditions

If Qp0zDumpTargetStack() is not successful, the return value usually indicates one of the following

errors. Under some conditions, the return value could indicate an error other than those listed here.

[EFAULT]

The address used for an argument is not correct.

In attempting to use an argument in a call, the system detected an address that is not valid.

While attempting to access a parameter passed to this function, the system detected an address

that is not valid.

[ESRCH]

No item could be found that matches the specified value.

Usage Notes





3. The Qp0zDumpTargetStack() can only safely be used against a thread that is stopped or waiting for

some activity to occur. If Qp0zDumpTargetStack() is used with a thread that is actively running, the

output stack trace may show an inconsistent view of the call stack.

4. If the target thread has more than 128 call stack entries, Qp0zDumpTargetStack() returns after

dumping the first 128 entries of the call stack.






Related Information


Data


Data



Example

The following example uses Qp0zDumpTargetStack() and Qp0zUprintf() functions to produce trace

output.





#include <milib.h>

#include <stdio.h>

#include <errno.h>

#include <unistd.h>



void *threadfunc(void *);


{

int rc=0;

pthread_t thread;

Qp0zUprintf("Entering Testcase\n");

rc = pthread_create(&thread, NULL, threadfunc, NULL);

sleep(2); /* Let the thread block */

/* If the other thread ends or is actively running (that is */

/* changing the call stack, you may get meaningless results in the*/

/* stack dump for the target thread.) */

Qp0zDumpTargetStack(thread.reservedHandle,

"Dumping target thread’s stack\n");

Qp0zUprintf("Exit with return code of 0\n");

return 0;

}

void foo(void);

void bar(void);

void *threadfunc(void *parm)

{

Qp0zUprintf("Inside secondary thread\n");

foo();

return NULL;

}

void foo(void)

{

bar();

}

void bar(void)

{

Qp0zDumpStack("Thread dumping my own stack\n");

sleep(10); /* Ensure the thread is blocked */

}

Trace Output:


JOB(107141/USER/TPZTSTK0) OUTPUT(*STDOUT). The above example program ran as job

107141/USER/TPZTSTK0.






record shown below, (the Entering Testcase trace point) was created by thread 0x36, and occurred




User Trace Dump for job 107141/USER/TPZTSTK0. Size: 300K, Wrapped 0 times.

--- 01/23/1998 12:38:10 ---

00000036:595584 Entering Testcase


00000037:598832 Inside secondary thread


00000037:599200 Stack: Thread dumping my own stack




00000037:805888 Stack: QP0WTEST / TPZTSTK0 TPZTSTK0 2 : threadfunc

00000037:806088 Stack: QP0WTEST / TPZTSTK0 TPZTSTK0 1 : foo

00000037:806288 Stack: QP0WTEST / TPZTSTK0 TPZTSTK0 1 : bar





--- 01/23/1998 12:38:12 ---

00000036:628272 Stack Dump For Target Thread: Handle 7 (0x00000007)

00000036:628464 Stack: Dumping target thread’s stack




00000036:652304 Stack: QP0WTEST / TPZTSTK0 TPZTSTK0 2 : threadfunc

00000036:652512 Stack: QP0WTEST / TPZTSTK0 TPZTSTK0 1 : foo

00000036:652712 Stack: QP0WTEST / TPZTSTK0 TPZTSTK0 2 : bar

00000036:677456 Stack: QSYS / QP0SSRV1 QP0SLIB 1061 : sleep

00000036:700096 Stack: QSYS / QP0SSRV2 QP0SWAIT 248 : qp0swait__FP13qp0ssigwait_t


00000036:700408 Exit with return code of 0




Qp0zLprintf()—Print Formatted Job Log Data


int Qp0zLprintf(char *format-string, ...);


The Qp0zLprintf() function prints user data specified by format-string as an information message type to

the job log.

If a second parameter, argument-list, is provided, Qp0zLprintf() converts each entry in the argument-list

and writes the entry to the job log according to the corresponding format specification in format-string. If

there are more entries in argument-list than format specifications in format-string, the extra argument-list

entries are evaluated and then ignored. If there are less entries in argument-list than format specifications

in format-string, the job log output for those entries is undefined, and the Qp0zLprintf() function may

return an error.

The data printed by Qp0zLprintf() is buffered one line at a time, and a new message in the job log is

forced every 512 characters if a new line (\n) is not detected in the data before that time. The buffer used

by Qp0zLprintf() is not physically written when the application ends. To ensure messages are written to

the job log, always use a new line (\n) at the end of each format-string.


intended for debugging exceptions or error conditions.


#TOP_OF_PAGE

aplist.htm

Parameters

format-string

(Input) The format string representing the format of the data to be printed. See the printf()

function in ILE C/C++ Run-Time Library Functions

for a description of valid format strings.

... (argument-list)

(Input) An optional list of arguments that contain entries to be formatted and printed to the job

log.

Authorities

None.

Return Value

value Qp0zLprintf() was successful. The value returned is the number of characters successfully printed.

-1 Qp0zLprintf() was not successful. The errno variable is set to indicate the error.

Error Conditions

If Qp0zLprintf() is not successful, errno usually indicates one of the following errors. Under some

conditions, errno could indicate an error other than that listed here.

[EINVAL]

The value specified for the argument is not correct.

A function was passed incorrect argument values, or an operation was attempted on an object

and the operation specified is not supported for that type of object.

An argument value is not valid, out of range, or NULL. An invalid format-string or argument-list

was specified.

[EFAULT]




that is not valid.

Usage Notes

None.

Related Information


Data


Data




Example

The following example uses Qp0zLprintf() to produce output in the job log.






#include <stdio.h>

#include <stdlib.h>

#include <unistd.h>




{


Qp0zLprintf("%.8x %.8x: Entered the %s thread\n",

pthread_getthreadid_np(), myData);

free(myData);

return NULL;

}


{


int rc=0;

char *threadData;






if (rc) {


exit(EXIT_FAILURE);

}




if (rc) {


exit(EXIT_FAILURE);

}






return 0;

}

Job Log Output:

The following two job log messages where generated by the example shown above. The output was

retrieved from the spooled file created when the job ran to completion and when the job log was

retained. The informational messages contain the contents of the Qp0zLprintf() function calls.

br>


*NONE Information 01/05/98 16:55:05 QP0ZCPA QSYS *STMT QP0ZCPA QSYS *STMT

From module . . . . . . . . : QP0ZUDBG

From procedure . . . . . . : Qp0zVLprintf

Statement . . . . . . . . . : 296

To module . . . . . . . . . : QP0ZUDBG

To procedure . . . . . . . : Qp0zVLprintf

Statement . . . . . . . . . : 296

Thread . . . . : 0000001A

Message . . . . : 00000000 0000001a: Entered the 50% Cotton, 50% Polyester thread

*NONE Information 01/05/98 16:55:05 QP0ZCPA QSYS *STMT QP0ZCPA QSYS *STMT

From module . . . . . . . . : QP0ZUDBG

From procedure . . . . . . : Qp0zVLprintf

Statement . . . . . . . . . : 296

To module . . . . . . . . . : QP0ZUDBG

To procedure . . . . . . . : Qp0zVLprintf

Statement . . . . . . . . . : 296

Thread . . . . : 0000001B

Message . . . . : 00000000 0000001b: Entered the Lacquered Camel Hair thread



Qp0zUprintf()—Print Formatted User Trace Data


int Qp0zUprintf(char *format-string, ...);


The Qp0zUprintf() function prints user data specified by the format-string parameter to the user trace.

If a second parameter, argument-list, is provided, Qp0zUprintf() converts each entry in the argument-list

and writes the entry to the user trace according to the corresponding format specification in format-string.

If there are more entries in argument-list than format specifications in format-string, the extra argument-list

entries are evaluated and then ignored. If there are less entries in argument-list than format specifications

in format-string, the user trace output for those entries is undefined, and the Qp0zUprintf() function may

return an error.







Parameters

format-string

(Input) The format string representing the format of the data to be printed. See the printf()

function in the ILE C/C++ Programmer’s Guide

for a description of valid format strings.


#TOP_OF_PAGE

aplist.htm

... (argument-list)

(Input) An optional list of arguments that contain entries to be formatted and printed to the user

trace.

Authorities

None.

Return Value

value Qp0zUprintf() was successful. The value returned is the number of characters successfully printed.

-1 Qp0zUprintf() was not successful. The errno variable is set to indicate the error.

Error Conditions

If Qp0zUprintf() is not successful, errno indicates one of the following errors. Under some conditions,

errno could indicate an error other than those listed here.

[EINVAL]

The value specified for the argument is not correct.

A function was passed incorrect argument values, or an operation was attempted on an object

and the operation specified is not supported for that type of object.

An argument value is not valid, out of range, or NULL. An invalid format-string or argument-list

was specified.

[EFAULT]




that is not valid.

Usage Notes










Related Information


Data


Data





Example

See “Qp0zDump()—Dump Formatted Storage Trace Data” on page 15—Dump Formatted Storage Trace

Data.



Join Trace (QSCJOINT) API


1 Set value Input Char(10)

2 Job identifier Input Char(40)

3 Return code Output Binary(4)

4 Error code I/O Char(*)

Default Public Authority: *USE Threadsafe: Yes

When *START is specified for the set value parameter, the Join Trace (QSCJOINT) API verifies if the job

passed in the job identifier parameter is being traced with JOINTRC(*YES) specified on the Start Trace

(STRTRC) command. If so, the trace characteristics of the specified job are used to modify the current job.

When *END is specified for the set value parameter, this API cleans the trace characteristics that were

previously set.




Service Watch function of the i5/OS®

operating system through System i™ Navigator’s

Application Administration support. The Change Function Usage (CHGFCNUSG) command, with

a function ID of QIBM_SERVICE_TRACE, can also be used to change the list of users that are

allowed to perform trace operations.


Set value

INPUT; CHAR(10)

The value passed to specify if the trace characteristics of the job passed in the job identifier

parameter will be set or cleared in the current job.

Special value Description

*START If the job passed in the job identifier parameter is being traced with JOINTRC(*YES) specified on

the Start Trace (STRTRC) command, the trace characteristics of the specified job are used to

modify the current job.

*END Clear the trace characteristics of the current job.

Job identifier

INPUT; CHAR(40)


#TOP_OF_PAGE

aplist.htm

The identifier of the job for which the trace environment is going to be verified if it was specified

to set its trace characteristics in a related job or thread. If *END was specified in the set value

parameter, this parameter must be set to hexadecimal zeros (’00’X). If *START was specified in

the set value parameter, the information must be in the following format:

Offset

Type Field Dec Hex

0 0 CHAR(10) Job name

10 A CHAR(10) User name

20 14 CHAR(6) Job number


28 1C BINARY(4) Thread indicator

32 20 CHAR(8) Thread identifier

Field Descriptions

Job name. The name of the job for which the trace environment is to be checked.

Job number. The number of the job for which the trace environment is to be checked.

Reserved. Must be set to hexadecimal zeros (’00’X).

Thread identifier. The identifier of a thread within a job for which the trace environment is to be

checked. This field must be set to hexadecimal zeros (’00’X) if thread indicator is set to 1.

Thread indicator. The value that is used to specify the thread within the job for which the trace

environment is to be checked. The following values are supported:

0 Use the thread specified in the thread identifier field.

1 Use the initial thread of the identified job.

User name. The name of the user of the job for which the trace environment is to be checked.

Return code

OUTPUT; BINARY(4)

The variable that receives the information requested.

Special value Description

0 Indicates the job passed in the job identifier parameter is being traced with JOINTRC(*YES)

specified on the Start Trace (STRTRC) command, therefore the trace characteristics of the

specified job were used to modify the current job.

1 Indicates the job passed in the job identifier parameter is not being traced with JOINTRC(*YES)

specified on the Start Trace (STRTRC) command, therefore the trace characteristics of the

specified job were not used to modify the current job.

Error code

I/O; CHAR(*)


parameter.

Error Messages




CPF136A E Job &3/&2/&1 not active.

CPF18BF E Thread &1 not found.

CPF3C3C E Value for parameter &1 not valid.

CPF3CF1 E Error code parameter not valid.

CPF98A2 E Not authorized to &1 command or API.



Problem Logging APIs

The Problem Logging APIs include:

v “Add Problem Log Entry (QsxAddProblemLogEntry) API” (QsxAddProblemLogEntry) adds additional

or supporting data to a problem log entry.

v “Change Problem Log Entry (QsxChangeProblemLogEntry) API” on page 36

(QsxChangeProblemLogEntry) updates an existing problem entry by changing the information.

v “Create Problem Log Entry (QsxCreateProblemLogEntry) API” on page 43

(QsxCreateProblemLogEntry) creates a problem log entry with the information provided to the

problem log entry.

v “Delete Problem Log Entry (QsxDeleteProblemLogEntry) API” on page 48

(QsxDeleteProblemLogEntry) deletes problem log entries or removes keys from a problem log entry.

v “End Problem Log Services (QsxEndProblemLogServices) API” on page 50

(QsxEndProblemLogServices) ends an instance of the problem log services identified by the handle

returned when the services started.

v “Log Software Error (QPDLOGER) API” on page 51 (QPDLOGER) logs a software problem and collects

data needed for its resolution.

v “Report Software Error (QpdReportSoftwareError) API” on page 55 (QpdReportSoftwareError) is an

ILE program that logs problems in the problem log and sends it to a service provider.

v “Retrieve Problem Log Entry (QsxRetrieveProblemLogEntry) API” on page 65

(QsxRetrieveProblemLogEntry) extracts data from a specific problem log entry.

v “Start Problem Log Services (QsxStartProblemLogServices) API” on page 68

(QsxStartProblemLogServices) sets up an environment for adding, creating, changing, deleting, and

retrieving problem log entries.

v “Work with Problem (QPDWRKPB) API” on page 69 (QPDWRKPB) analyzes and prepares a

machine-detected hardware problem for reporting.


Add Problem Log Entry (QsxAddProblemLogEntry) API


1 Handle Input Binary(4)

2 Key structures Input Array of Pointers

3 Number of keys Input Binary(4)



#TOP_OF_PAGE

aplist.htm

#TOP_OF_PAGE

aplist.htm

Default Public Authority: *USE Service Program: QSXSRUPL Threadsafe: No

The Add Problem Log Entry (QsxAddProblemLogEntry) API adds information to an existing problem log

entry.

The API supports the following data types:

v Keys 2001-2009 (field replaceable unit (FRU) entries) can be added to the problem log entry.

v Keys 4001 and 4002 (supporting data) entries can be added. Do not add duplicate information because

checking is not performed.

v Key 6001 (history information) can be added.

v Key 7001 (PTF ID) can be added to a problem log entry. If the PTF entry already exists, an error is

signalled.


API Public Authority

*USE


Handle

INPUT; BINARY(4)

An identifier that associates the problem log services started by the Start Problem Log Services

API.

Key structures

INPUT; ARRAY of POINTERS

An array of pointers that has the address of each key that contains data to be written into the

problem log. The number of pointers passed in the array must equal the value passed by the

Number of keys parameter. Keys not supported for the Add Problem Log Entry API cause error

messages to be sent to the caller.

Number of keys

INPUT; BINARY(4)

Number of keys passed to the API.

Error code

I/O; CHAR(*)


parameter.

Rules for Key Usage

Key 1 (problem log ID) is required to identify the problem log entry to process.

Data can be added to an existing problem log entry with the Add Problem Log Entry API. The types of

data that may be added with this API are:

v Keys 2001-2009 (FRU entries)

v Supporting data entries (keys 4001 and 4002 (supporting data)

v Key 6001 (history information)

v Key 7001 (PTF ID)


The remaining data contained in a problem can be altered using the Change API. More information on

the above keys can be found in “Key Groups for Problem Log APIs” on page 167.

Keys for Adding FRU Records

A FRU, field replaceable unit, entry defines an object that may have a specific machine-detected problem.

FRUs have been broken into 9 types and represented by keys 2001 through 2009.

The types are:

2001 Device FRU type

2002 Code FRU type

2003 Media FRU type

2004 User FRU type

2005 FRU name

2006 Attached FRU

2007 Configuration FRU

2008 General FRU

2009 Channel attached FRU

In addition, a FRU or list of FRUs are associated with a problem based upon an analysis class. The

analysis class implies the amount or type of analysis that has been done on the problem. FRUs are

associated with a problem within the context of a class.

The classes of FRUs are:

1 Point of failure

2 Partial isolation

3 Isolation

4 Verification

5 Recovery

6 Answer

To add FRUs for a class of FRUs, the problem log entry must be identified, the class must be chosen, and

the data must be added. These three actions need to be done for each FRU type. FRUs may be used in

any combination, to add data about individual failing elements to a maximum of 21 FRUs per class.

This API adds FRU entries to the bottom of the list. If they need to be maintained in probability order,

follow these steps:

v Retrieve the group using the Retrieve Problem Log Entry API.

v Modify the FRU records or append additional FRUs to the original list.

v Delete the existing FRU entries of that class using the Delete Problem Log Entry API.

v Add the new or updated FRU list using the Add Problem Log Entry API.

Keys for Adding Supporting Data

The addition of supporting data is not restricted. Any number of spooled or data base files can be

associated with a problem log entry. Duplicate records are allowed. If you add a file twice, it is listed

twice.

To add supporting data, define the type of record to be added using keys 4001 and 4002 (supporting

data). They can be added in any combination.

Keys for Adding History Data

The addition of history data, or events, is restricted because specific events can occur only when the

problem is in a specific status. Some history data types are applicable to specific problem log types. Any


number of events can be associated with a problem log entry. Duplicate records are allowed since many

events can be repeated. Events are added in the sequence that you supply them on the API call. The API

makes no attempt to put them in order.

To add a history entry, use key 6001 (history information) to supply the needed data to reflect the action

that was taken. If you are adding supporting data, you can add it in any combination. The time the event

is added is entered by the API.

The history types are:

0 Problem entry closed. Only applicable when the problem has been closed. Once this status is set, the problem

can only be retrieved.

1 Problem entry opened. Can only be used when the problem is initially opened.

2 Service request received. Only applicable when a problem is received from another system.

3 Opened by an alert. Only applicable when the problem is opened due to an alert.

4 Problem analyzed. Applicable each time a problem is analyzed.

5 Verification test ran. Applicable each time a problem is verified.

6 Recovery procedure ran. Applicable each time recovery is run.

7 Prepared to report. Applicable each time a problem is prepared to be sent to a service provider.

8 Service request sent. Applicable only when a problem is sent to another system. This implies that the service

request was sent, but the service provider has no solution to the problem.

9 Problem answered. Applicable only when a problem is sent to another system. This implies that the service

request was sent, and the service provider has a solution to the problem.

10 Response sent. Implies that a reply has been received from a service provider.

11 Reported by voice. Used when a problem is reported manually.

12 Fixes transmitted. Implies that fixes have been sent to a service requester.

13 A change request was submitted for this problem.

14 The change request submitted for this problem has ended.

15 Fix verified. Applicable each time a problem is verified.

16 Remote analysis. Only applicable when a problem has been analyzed by a remote service representative.

17 Remote verification ran. Only applicable when this system has been used to analyze a problem on another

system.

18 Remote recovery ran. Only applicable when this system has been used to perform recovery on another

system.

19 Alert created. Only applicable when the system created an alert for this problem.

20 APAR created. Only applicable when APAR data is created during analysis.

21 APAR data collected. Only applicable when APAR data is collected during analysis.

22 APAR data restored. Only applicable when APAR data is restored during analysis.

23 APAR data deleted. Only applicable when APAR data is deleted during analysis.

24 Changed by CHGPRB. Only applicable when the problem was changed by the CHGPRB command or the

QsxChangeProblemLogEntry API.

25 Deleted by DLTPRB. Only applicable when the problem was changed by the DLTPRB command or

QsxDeleteProblemLogEntry API.

26 This problem has occurred multiple times.

27 Status changed. Only applicable when querying the status of a problem that has been reported to a service

provider.

28 Status query sent. Only applicable when querying the status of a problem that has been reported to a service

provider.

29 Automatic problem analysis has completed successfully.

30 Auto-PAR is not complete; the SRC flag is off. Problem analysis did not occur because the SRC was turned

off.

31 Auto-PAR not complete, submit job to QSYSWRK failed.

32 Auto-PAR failed. Problem analysis failed because an unknown problem occurred.

33 Auto-Notify complete. Problem was sent automatically.

34 Auto-Notify not complete, SRC flag is off. Problem was not sent automatically, the SRC was turned off.

35 An attempt to automatically send the problem failed.

36 Auto-Notify failed.


37 Problem analysis failed.

See the Basic system operations topic collection for more information about SRCs.

Keys for Adding PTF Entry

PTF entries can be added to the problem log at any time. Duplicate PTF records are not allowed and

signal an exception condition. To ensure uniqueness, the PTF identifier and the product data are required.

To add a PTF record, use key 7001 (PTF ID) to add the data required. The PTF entry is added to the

bottom of existing text.

To get the PTF records in a specific order, the records must be retrieved, sorted and then replaced after

the existing PTF records are deleted.

PTF entries can be created using *ONLY*PRODUCT** as the constant for Product ID and *ONLY as the

constant for version, release, and modification level.

Error Messages


CPF3C1E E Required parameter &1 omitted.

CPF3C90 E Literal value cannot be changed.


CPF3CF2 E Error(s) occurred during running of &1 API.

CPF7AAB E Problem &1 not found.

CPF3C4D D Length &1 for key &2 not valid.

CPF3C82 D Key &1 not valid for API &2.

CPF3C86 D Required key &1 not specified.

CPD7A82 D Value not valid for key &1. (char string)

CPD7A83 D Value not valid for key &1. (integer)

CPD7A88 D Incorrect DBCS field format found.

CPD7A8A D Key value &1 is not valid.

CPF7A89 E Incorrect handle for this activation.

CPF7A8A E Problem log services not started.

CPF7AA7 E Problem &1 not found.

CPF9821 E Not authorized to program &1 in library &2.

CPF9872 E Program or service program &1 in library &2 ended. Reason code &3.

CPFA320 E Pointer parameter is null.



Change Problem Log Entry (QsxChangeProblemLogEntry) API






Default Public Authority: *EXCLUDE Service Program: QSXSRVPL Threadsafe: No


#TOP_OF_PAGE

aplist.htm

The Change Problem Log Entry (QsxChangeProblemLogEntry) API updates an existing problem entry by

changing the information. Key 1 (problem log ID) identifies the problem to be changed. Some data in the

problem log entry can be changed on a field by field basis while other data can only be changed as a

group and some data cannot be changed.



*USE


Handle

INPUT; BINARY(4)

An identifier that associates the problem log services started with the

QsxStartProblemLogServices API.

Key structures


An array of pointers to the key structures being passed to the API.

Number of keys

INPUT; BINARY(4)

Number of keys passed to the API.

Error code

I/O; CHAR(*)


parameter.

Format of the Keys

The number of keys used varies depending on the type of problem log entry being changed. You must

select the keys applicable to the problem type with which you are working. If the keys provided to the

API do not match the requirements for the problem log entry type you are changing, you are notified by

the error handling procedures.

For details about the keys that can be used, see “Key Groups for Problem Log APIs” on page 167.

Rules for Key Usage

You can change the problem log data, the status, or both. The problems are categorized into the following

types:

1 Machine-detected problem

2 User-perceived hardware or software problem

3 PTF orders

4 User-perceived remote problem

5 Application-detected problem

6 Client machine-detected problem

7 Client user-detected problem

8 User-created general problem

Changing General Data

General data is data that can be changed for any problem type without affecting the status of the

problem. Data of this class are:


v Key 4 (user assigned). The validity of this data is not checked.

v Key 3001 (text entry) problem types 1, 2, and 4 can be changed.

v Key 6001 (history information). Use the Add Problem Log Entry (QsxAddProblemLogEntry) API.

Changing Problem Status

To change the problem status, specific data is required. The amount of data depends on the current or

requested problem log status. Data that requires a status change cannot be added unless key 3 (problem

status) is provided. An error is signaled if this occurs.

A problem can be changed to the following statuses:

v OPENED

The beginning status of a problem.

v OPENED-PREPARED

Problem is staged for transmission to a service provider.

v READY

Problem entry has been analyzed and data is provided by keys that reflects the analysis results.

v READY-PREPARED


v SENT

Problem has been sent to a service provider and a solution was not available.

v SENT-PREPARED


v ANSWERED

Problem has been sent to a service provider and a solution was available.

v ANSWERED-PREPARED


v VERIFIED

User has applied and tested the solution provided. The results of the testing are satisfactory. Once a

problem is moved to VERIFIED status, it cannot be returned to OPENED or READY status.

v VERIFIED-PREPARED


v CLOSED

Problem is resolved and there is no longer a need for the problem entry. Once this status is set, it

cannot be returned to any other status. The problem can only be retrieved.

PREPARED, while displayed as a specific status, is actually an amplifier to the previous status of the

problem: OPENED, READY, SENT, ANSWERED or VERIFIED.

The supplemental data needed to move a problem to PREPARED status are:

v Key 6 (operational data)

– Prepared for system

Required to define the system that this problem will be sent to.v Key 1001 (problem severity)

– Optional. If not provided, the API defaults it to None.

– Prohibited for PTF orders (problem type 3).v Key 1011 (PTF media selection)


Optional. Defines the media on which a program fix can be delivered. If not provided, the contact data

is used as a default. Typically this is the tape device type and model or a description of the media type

on which PTFs are delivered if the distribution size exceeds a predefined transmit size limit.

v Key 5001 (contact information)

Optional. Used to override local service contact information.

A problem can be set to PREPARED status by providing the required data keys (if not already provided)

and a key 3 (problem status) code of 5.

Keys for Changing Problem Type 1 to Another Status

Problem type 1 (machine-detected problems) requires data from two additional key groups, 1000 and

2000.

Note: When changing status and FRU entries are required, use the Add Problem Log Entry API. To

change status in general, you do not need the key group 2000 data.

v Data for OPENED status

A problem in OPENED status, with the exception of general data that does not affect a status change,

can only be changed to READY status. A problem may be changed from the OPENED status to the

PREPARED status if the problem is to be sent to a system that has System Manager installed.

v Data for READY status

A problem can be changed from OPENED to READY status by including the following data items:

– Key 3 (problem status) indicates READY status.

– Key 1004 (reporting device) is always required to identify the product with a maintenance contract,

regardless of the problem.

– Key 1006 (reporting code) is required for problems that were, on analysis, determined to be caused

by software.

– Key 1010 (symptom string).

– Key 1007 (problem analysis data).v Data for SENT and ANSWERED status at the service requester

A problem can be changed to SENT or ANSWERED status by including the following data items:

– Key 3 (problem status) indicates SENT or ANSWERED status.

– Key 8 (answer codes).

At the service requester the answer code assigned field should be updated with the answer received

from a service provider that is not *IBMSRV.

If *IBMSRV was the service provider, the Problem number field should be updated to reflect the

problem management number that *IBMSRV has associated with the problem.

– Key 7001 (PTF ID) is used to change the Sent and Status fields.

Once the problem is in SENT or ANSWERED status, text can be added that defines the problem status.

This is data that is added as a response to a query of the problem status or as an answer the service

provider sends to the problem. This is done with key 3001 (text entry), type 3. Key 6001 (history

information) is required to indicate the action has taken place.

If the local system is acting as a service provider, the problem log entry for the service requester can be

updated to reflect the following conditions:

– A response was sent

– PTFs were sent

– An answer was added to the problem log

These actions do not require a status change. Add a history event to define the action taken.

v Data for ANSWERED status at the service provider

When a service provider answers a problem, the status is changed from READY status to ANSWERED

status by including the following data items:


– Key 3 (problem status) indicates ANSWERED status.

– Key 6001 (history information) can add a number of events depending on the status change.

– Key 7001 (PTF ID) is used to change the Sent and Status fields of the PTF entry.

Once the problem is in ANSWERED status, text can be added that defines the problem status. This is

data that is added as a response to a query of the problem status or as an answer the service provider

wants to add to the problem. This is done with key 3001 (text entry), type 3. Key 6001 (history


When a response is sent to the service requester, key 6 (operational data) is used to indicate that a

response was sent. The following data items are required:

– Key 8 (answer codes) is updated to indicate the answer that was sent to the service requester.



If PTFs were sent or an answer was added to the problem log, these actions do not require a status

change. Add a history event to define the action taken.

v Data for VERIFIED status

A problem can be changed to VERIFIED status from READY, SENT or ANSWERED status by including

the following data items:

– Key 3 (problem status) indicates VERIFIED status.

– Key 1008 (fix verification status) where the Status field and PDP field must be provided.

– Key 6001 (history information) can add a number of events depending on the status change. The

Remote verification ran field is required based on the origin system location.

– FRUs (key group 2000) are added for machine-detected problems and are added with the Add

Problem Log Entry API.v Data for recovery

Recovery data can be added from OPENED or READY by including the following data items, and the

status is not changed:

– Key 3 (problem status) is not permitted. The status does not change as a result of running recovery

procedures.

– Key 1009 (fix recovery status) and problem determination procedures (PDP) fields must be provided.

– Key 6001 (history information) can add a number of events depending on the status change. Remote

recovery ran is required based on the origin system location.v Data for CLOSED status

A problem can be changed to CLOSED status from any other status by including the following data

items:

– Key 3 (problem status) indicates that CLOSED status is the only key allowed.

– Key 6 (operational data) is updated by the API when the problem is closed.

Keys for Changing Problem Types 2, 4, 5, and 8

Problem types 2 (User-perceived), 4 (User-perceived remote), 5 (Application-detected), and 8

(User-created general) require the following data to achieve the following status:


This does not apply because these problem types are created in READY status.


This does not apply because these problems are created in READY status.

v Data for SENT and ANSWERED status at the service requester





At the service requester, the Answer code assigned field should be updated with the answer

received from a service provider that is not *IBMSRV.

If *IBMSRV was the service provider, the problem management number (PMR) number field should

be updated to reflect the problem management number that *IBMSRV has associated with the

problem.








updated to reflect that a response was sent, PTFs were sent, or that an answer is added to the problem

log. These actions do not require a status change. Add a history event to define the action taken.





– Key 6001 (history information) can add a number of entries depending on the status change.






When a response is sent to the service requester, the problem log entry is updated to reflect that a







v Data for CLOSED status


items:



Keys for Changing Problem Type 3

Problem type 3 (PTF order) requires the following data to achieve the following status:


This does not apply to PTF orders (problem type 3).


This does not apply to PTF orders (problem type 3) because they are created in READY status.

v Data for SENT and ANSWERED status at the service requester




At the service requester the Answer code assigned field should be updated with the answer received

from a service provider that is not *IBMSRV.


If *IBMSRV was the service provider, the Problem number field should be updated to reflect the

problem management number that *IBMSRV has associated with the problem.


– Key 7001 (PTF ID) is used to change the Sent and Status fields. This key is also used to update the

product and VRM fields of the PTFs, especially if the default product, *ONLYPRD, and version,

*ONLY, were used during the creation of the problem or if the SNDPTFORD command used the

defaults.






updated to reflect that a response was sent, PTFs were sent, or that an answer is added to the problem

log. These actions do not require a status change. Add a history event to define the action taken.











When a response is sent to the service requester, the problem log entry is updated to reflect that a







v Data for CLOSED status


items:



Keys for Changing Problem Types 6 and 7

Problem type 6 (client machine-detected) and problem type 7 (client user-detected) require the Problem

category field in key 1012 be set to 0 (Report) to move to PREPARED status.

Error Messages














CPD7A87 D Key &1 may be added only once.



CPD7A8B D Length of data not valid.









Create Problem Log Entry (QsxCreateProblemLogEntry) API



2 Problem log ID Output Char(40)




Service Program Name: QSXSRVPL Default Public Authority: *USE Threadsafe: No

The Create Problem Log Entry (QsxCreateProblemLogEntry) API creates a problem log entry and adds

the information provided to the problem log files using keys. Key 1 (problem log ID) is returned to the

user that is required for other API operations.

The API allows a problem to be created with a status of OPENED, READY, or PREPARED. The difference

to the user is that the amount of data increases as the problem goes from OPENED to PREPARED.

The types of problems that may be created are:

v Machine-detected (problem type 1)

v User-perceived (problem type 2)

v PTF orders (problem type 3)

v User-perceived remote hardware or software problems (problem type 4)

v Application-detected (problem type 5)

v Client machine-detected (problem type 6)

v Client user-detected (problem type 7)

v User-created general (problem type 8)

The keys provided to create a problem are checked for validity and applicability to the problem log entry

in two ways:

v Applicability of the type


#TOP_OF_PAGE

aplist.htm

v Applicability of the field

The fields are checked to verify that they are not null. Some keys allow the user to control them (key

control). Keys without ″key control″ support require all fields to be filled. Fields not flagged are

ignored.(The existence of the data is verified; NOT whether or not the data is valid. The problem log

APIs do not check the validity of the data.) Operations that are unsupported or not valid, such as

creating a problem in SENT status or not providing all dependent keys, result in a diagnostic message for

each infraction found and an exception or an error notification defining it.

The key fields are checked before the problem log entry is created and an error is signalled if any

required key fields are null.

If the maximum number of problem log entries has been reached for this particular date (99999), CPF392F

E is signaled.



*USE


Handle

INPUT; BINARY(4)

An identifier that associates the problem log services started by the Start Problem Log Services

API.

Key 1 (problem log ID)

OUTPUT: CHAR(40)

This parameter contains the problem log identifier after the problem is created. If this parameter

is omitted, no problem log ID is returned.

Key structures


An array of pointers that has the address of each key that contains data to be written into the

problem log. The number of pointers passed in the array must equal the value passed by

parameter 4, Number of keys.

Number of keys

INPUT; BINARY(4)

Defines the number of keys that are being passed to the API.

Error code

I/O; CHAR(*)


parameter.

Format of the Keys

See “Key Groups for Problem Log APIs” on page 167 for a description of the keys.

Rules for Key Usage

To create a problem log entry, specific data is required. The amount of data varies depending on the

status of the problem log. This section defines the data required for each problem type for statuses


OPENED and READY. Problems in OPENED or READY status may be amplified with the status of

PREPARED. The supplemental data required for this is defined once and is applicable to either OPENED

or READY.

General Keys For Problem Log Entry Data

The minimum key data for all problems types is:

v Key 1 (problem log ID)

This key must contain one of the following:

– Problem log identifier if the problem was created on another system

– The value ″*LOCAL″ to indicate that the problem is a local one.v Key 2 (problem type)

This defines the type of problem log entry being created.

v Key 3 (problem status)

Defines the status to which the entry will be set. Three values are allowed:

– OPENED. Create a problem in OPENED status.

– READY. Create a problem in READY status.

– PREPARED. Create a problem in READY or OPENED status and add supplemental data required

for PREPARED status.v Key 5 (problem origin system)

– Required if key 1 (problem log ID) is not *LOCAL.

– Prohibited if key 1 (problem log ID) is *LOCAL.v Key 6 (operational data)

– If key 1 (problem log ID) is *LOCAL, the Received from system field is prohibited. If it is not

*LOCAL, the Received from system field is required.

– If key 3 (problem status) indicates the problem is to be in PREPARED status the Prepared for system

field is required otherwise it is prohibited.

– The Date and time added field is automatically added by the API.

– The Date and time closed field is automatically added when the problem is closed.v Key 1002 (problem description message) or key 3001 (text entry), type 1.

Either or both are acceptable. Key 3001 is used if both are supplied. When both key 1002 and key 3001

are added, only key 3001 is available through the command interface, but both key 1002 and key 3001

can be retrieved through APIs. When the problem type is machine detected, key 1002 is required.


Required if key 1 (problem log ID) is not *LOCAL. Used to enter contact data for the remote system.

v Key 6001 (history information)

This information defines the type of create action. One or more history entries are allowed. At least one

event is required.

In addition, the following information is needed based on the problem type.

Keys for Creating Problem Type 1

Machine detected problems (problem type 1) use the following keys:

Data for OPENED status are:

v Key 1002 (problem description message)

Required.

v Key 1003 (problem creation data)

Required.

v Key 1005 (failing device)


Required to define the device and/or code that is failing.


At least one key of the range 2001 to 2009 is required. The keys may be provided in any order but will

be stored in probability of fix order, with the highest probability FRU record being stored first and the

least probability FRU record being stored last.

v Keys 4001 and 4002 (supporting data)

Optional. Used to define the supporting data that will be associated with the problem. Multiple entries

are allowed.v Data for READY status are:

Post analysis data must be added to a machine detected problem to achieve READY status. This data is

in addition to the data added to achieve OPENED status. Data for READY status are:

v Key 1004 (reporting device)

Defines the machine that will be reported to a service provider as the failing machine.

v Key 1005 (failing device) This provides a description of the resource that caused the problem.

v Key 1006 (reporting code)

Defines the program/product that is failing. This is required if the highest probability FRU is key 2002

(code FRU type).

v Key 1007 (problem analysis data)

Required

v Key 1010 (symptom string)

Required


At least one key of the range 2001 to 2009 is required. The keys may be provided in any order but will

be stored in probability of fix order, with the highest probability FRU record being stored first and the

least probability FRU record being stored last.


User-perceived hardware or software problems (problem type 2) can be created in READY and READY -

PREPARED status only. These problems require data similar to machine-detected problems (problem type

1) with the following exceptions:

v Key group 2000 (FRU records) is prohibited.

v Key group 3000 (problem type 1) is required if 1002 is not used.


PTF orders (problem type 3) are created in READY and READY - PREPARED status only and use the

following:

v Key group 1000 (problem description entries), except key 1002 (problem description message), is

prohibited.


v Key group 4000 (supported data records) is prohibited.

v Key 1011 is optional.

v Key group 7001 is required.


User-perceived remote hardware or software problems (problem type 4) can be created in READY and

READY - PREPARED status only. These problems require data similar to machine-detected problems

(problem type 1) with the following exceptions:


v Key group 4000 (supported data records) is prohibited.



Application detected problems (problem type 5) are used to enter problems automatically detected during

the execution of a program. They can be created in READY and PREPARED status only. These problems

require data similar to machine-detected problems (problem type 1) with the following exceptions:

v Key group 2000 (FRU records) is optional.

If key group 2000 (FRU records) is specified only key 2002 (code FRU type) is permitted.

v Key group 4000 (supported data records) is optional.

Key group 4000 (supported data records) may be used to identify APAR data that is associated with

the problem.

Keys for Creating Problem Types 6 and 7

Client machine-detected (problem type 6) and user-created (problem type 7) problems are used to create

problem log entries for an attached client. These problems are generated in the READY status. The data

requirements are:

v Key 1012 is required and must be LOGONLY on the Add Problem Log Entry API.

v Key 1013 is required.

v Key 1003 (problem creation data)

v Key 1010

v Keys 1001, 1002, 1003

v Keys 4001 and 4002 are optional

v Key 3001 (text entry) is optional

v Key 6001 (history information) is optional


User-created general problems (problem type 8) are used to add data of a general nature, that is not

applicable to the types already defined. The entry can be created in READY and READY - PREPARED

status only. The data requirements are:

v Key group 1000 (problem description entries) is prohibited.

v Key 1002 (problem description message) can be used to create text for the problem description of the

message.

v Key 3001 (text entry) type 2 is required to provide a detailed description of the problem.

Key group 4000 (supported data records) can be used to identify data that is associated with the

problem.

Data for PREPARED Status

The supplemental data needed to move a problem from OPENED or READY status to PREPARED status

are:

v Key 6 (operational data)

v Key control

v Prepared for system

Required to define the system that this problem will be sent to.

v Key 1001 (problem severity)

v Optional. Default is none.

v Ignored for PTF Order (problem type 3).

v Key 1011 (PTF media selection)

Optional. Default is the contact data base. Typically this is the tape device type and model or a

description of the media type on which PTFs are delivered if the distribution size exceeds a predefined

transmit size limit.



Optional. Used to override local service contact information.

Error Messages















CPD7A8B D Length of data not valid.









Delete Problem Log Entry (QsxDeleteProblemLogEntry) API






Default Public Authority: *USE Service Program: QSXSRVPL Threadsafe: No

The Delete Problem Log Entry (QsxDeleteProblemLogEntry) API provides one of the following functions:

v Deletes a single problem log entry.

The problem log entry and all associated data is deleted.

v Removes data from a problem log entry.

The data that can be removed by the API are:

v Key group 2000 (FRU entries). Either all FRU entries or all FRU entries of a class are removed.

Individual FRU entries cannot be removed.

v Key group 4000 (supported data entries). Either all supporting data entries are removed or all entries

of a type.

v PTF entries can be deleted individually, using key 7001 (PTF ID), or they can be deleted entirely using

key 7000 (PTF entry).


#TOP_OF_PAGE

aplist.htm



*USE


Handle

INPUT; BINARY(4)



Key structures

INPUT; Array of Pointers

Array of pointers to the data contained in each key being passed to the API.

Number of keys

INPUT; BINARY(4)

Tells the API how many keys are being passed to it.

Error code

I/O; CHAR(*)


parameter.

Format of the Key Groups

Depending on the type of problem entry being deleted, one or more key groups must be provided to

remove the data required or desired to the problem. You must select the keys applicable to the problem

data you are deleting. If the keys provided to the API do not match the requirements for the problem log

entry type you are deleting, you are notified by the error handling procedures.

For details about the keys that may be used see “Key Groups for Problem Log APIs” on page 167.

Rules for Key Usage

The Delete Problem Log Entry API can be used to:

v Delete the problem log entry.

v To delete specific entries from the problem log.

The specific data that can be deleted are:

– Key 2000 (class of FRU entries) to remove all FRU entries or all FRU entries of a class

– Key 7000 (PTF entry) to remove all PTF entries

– Key group 4000 (supporting data entries) to remove all supporting data entries, or all spooled file

entries or all data file records as a group. Individual entries cannot be removed.

– Key 7001 (PTF ID) to remove a single PTF entry

Deleting the above in any combination is supported.

The status of a problem log is not changed as a result of the delete operation.

Delete a Problem Log Entry

To delete a problem log entry, provide a key 1 (problem log ID) with no other keys. This deletes the

problem log entry and all associated data. To delete the problem, it must be in CLOSED status or be

older than the period defined by system value QPRBHLDITV.


Delete FRU Entries

Individual FRU entries cannot be deleted. FRU entries are deleted by class. For example, to delete the

point of failure FRUs, use key 2000 and set the class field to 1. All point of failure FRUs are deleted.

Delete PTF Entries

PTF entries can be deleted individually, using key 7001 (PTF ID), or they can be deleted entirely using

key 7000 (PTF entry).

Delete Supporting Data

Individual supporting data entries cannot be deleted. The entry in the problem log is deleted and the

data defined by the entry is also deleted. For example, if a spooled file entry is defined, the problem log

contains the name of the object to be deleted. The spooled file and the problem log entry containing the

spooled file name are both deleted. Provide the following data:

v Key 1 (problem log ID)

v Key group 4000 (supported data entries) deletes all entries or all entries of a type.

Error Messages










CPF7AA6 D Problem record &1 cannot be deleted.



CPD7A89 D Record &1 was not deleted.




CPF7AA6 E Problem record &1 cannot be deleted.







End Problem Log Services (QsxEndProblemLogServices) API

Required Parameter





#TOP_OF_PAGE

aplist.htm

The End Problem Log Services (QsxEndProblemLogServices) API ends an instance of the problem log

services identified by the handle returned when the services were started. The following are performed:

v A rollback is issued to delete any problem log entries that were not committed. This is just performed

as a precaution only. The Add, Change, Create, and Delete Problem Log Entry APIs perform a commit

or rollback.



*USE

Required Parameter

Handle

INPUT; BINARY(4)

The handle that defines the instance of problem log services to end.

Error code

I/O; CHAR(*)


parameter.

Error Messages











Log Software Error (QPDLOGER) API


1 Suspected program name Input Char(10)

2 Detection ID Input Char(12)

3 Message reference key Input Char(4)

4 Point of failure Input Binary(4)

5 Print job log Input Char(1)

6 Data items Input Char(*)

7 Data item offset and length Input Array of Char(*)

8 Number of data items Input Binary(4)

9 Object name Input Array of Char(*)

10 Number of object names Input Binary(4)




#TOP_OF_PAGE

aplist.htm

12 ILE module name Input Char(10)


13 Problem log entry creation Input Char(1)

Default Public Authority: *USE

Threadsafe: Conditional; see “Usage Notes” on page 54.

The Log Software Error (QPDLOGER) API allows a program to report a software problem to the local

System i™ platform and provide the data needed to resolve the problem. When this API is called, any

error data provided is spooled to one or more spooled files, a symptom string is created, an entry is

created in the problem log, and a message is sent to the QSYSOPR message queue indicating that a

software error has been detected.

Error data can be provided on the API call by using the data item offset and length and object name

parameters.




Service dump function of i5/OS®

through System i™ Navigator’s Application Administration

support.

Object Authority

Read data authority to the object to be dumped.

Locks None.


Suspected program name

INPUT; CHAR(10)

The name of the program in which the error is suspected. Service programs are not supported.

The Report Software Error (QpdReportSoftwareError) API must be used to report a problem

against a service program. If a service program is specified on the QPDLOGER API, the service

program will not be found and the suspected program will be used instead.

Valid values are:

*SAME The reporting program.

*PRV The program that called the reporting program.

program name The name of the suspected program.

The suspected program name is included in the symptom string (as F/name) created when this

API is called.

Detection ID

INPUT; CHAR(12)

A message ID or other value defined by the reporting program that further identifies the

problem. This value is included in the symptom string (as MSGdetectionid) created when this API

is called.


Message reference key

INPUT; CHAR(4)

The message key associated with the message that is being reported (if a message is being

reported). This parameter is used to verify that message CPF9999 (a function check) was not

caused by a damage exception (CPF81xx). If message CPF9999 is caused by a damage exception,

the problem will not be reported. This value is ignored if it does not contain a key for a CPF9999

message.

Note: The detection ID should not contain blanks. The API ignores characters after the first blank.

Point of failure

INPUT; BINARY(4)

A return code, statement number, or other value defined by the reporting program that assists in

locating the problem. This value is converted to zoned decimal and included in the symptom

string (as RCnnnnnnnn) created when this API is called.

Print job log

INPUT; CHAR(1)

Whether the job log and other job information is to be spooled to a spooled file.

Valid values are:

Y Print the job log and job information.

N Do not print the job log and job information.

Data items

INPUT; CHAR(*)

The data to be spooled.

Data item offset and length

INPUT; ARRAY of CHAR(*)

An array of the offsets to and lengths of the data items to be spooled to a spooled file. The array

can contain up to 32 elements.

Each element has the following structure:

Data offset BINARY(4).

The offset to the data item from the start of the data.

Data length BINARY(4).

The length of this data item (must be greater than 0).

Number of data items

INPUT; BINARY(4)

The number of elements in the array of data item offsets and lengths. The number must be

between 0 and 32, inclusive.

Object name

INPUT; ARRAY of CHAR(*)

An array of object names whose contents are to be spooled to a spooled file. The array can

contain up to 32 elements.

Each element has the following structure:

Object name CHAR(30).

The name of the object to be spooled.

Library CHAR(30).


The library in which the object resides.

Valid values for the library name are:

*CURLIB

The job’s current library.

*LIBL The library list.

library name

The specific library that contains the object.

Object type CHAR(10).

The object type. For a complete list of the available object types, see Object Types in the CL topic.

Number of object names

INPUT; BINARY(4)

The number of object names in the array of object names. The number must be between 0 and 32,

inclusive.

Error code

I/O; CHAR(*)


parameter. If this parameter is omitted, diagnostic and escape messages are issued to the

application.


ILE module name

INPUT; CHAR(10)

The name of the integrated language environment (ILE) module in which the error is suspected.

This value is included in the symptom string created when this API is called.


Problem log entry creation

INPUT; CHAR(1)

Whether a problem log entry is created or not.

Valid values are:

0 Unconditional - Create a problem log entry. This is the default value when this parameter is not

present.

1 Conditional - Do not create a problem log entry.

Usage Notes

When this API runs within a threaded job, the Print job log parameter is ignored and the dump is

done of the current thread job.


Error Messages




CPF93C0 E Software error logging not active.

CPF93C2 E &1 is not a valid number of data items.

CPF93C3 E &1 is not a valid number of object names.

CPF93C4 E Error already logged.

CPF93C5 E Software problem logging (QPDLOGER) API error occurred.


CPI93B2 I Software problem data for &4 has been detected.

CPI93CA I Suspected program &1 not found.

CPI93CB I Point-of-failure value not valid.

CPI93CC I Object &1 in library &2 not found.

CPI93CF I Data length or data offset not valid.



Report Software Error (QpdReportSoftwareError) API


1 Problem description records Input Array of Pointers

2 Number of problem description records Input Binary(4)


Default Public Authority: *USE Service Program: QPDSRVPG Threadsafe: Conditional; see “Usage Notes” on page 64.

Use the Report Software Error (QpdReportSoftwareError) API whenever your ILE program detects a

software problem that must be fixed.

The API logs the problem in the system problem log, which lets you track the problem, as well as send it

to a service provider. See the IBM®

System Manager for i5/OS®

licensed program for more information

about service providers and service requesters.

The API also lets you specify the symptoms that identify the problem. The operating system and the

service provider use those symptoms to find a PTF that may fix the problem.

The API also lets you specify data to dump to spooled files. If neither the operating system nor the

service provider can find a PTF, you may be able to find the cause of the problem using the data the

program dumped.


Object Authority

*USE for objects in libraries

*R for objects in directories

Object Library Authority

*EXECUTE


#TOP_OF_PAGE

aplist.htm

Object Directory Authority

*RX

Locks None


Problem description records


This is a list of pointers to problem symptom and data description records. See “Problem

Description Records Format” for the format of the records.

Number of Problem description records

INPUT; BINARY(4)

The number of problem description records your program is passing to the API.

Error code

I/O; CHAR(*)


parameter. If this parameter is omitted, diagnostic and escape messages are issued to the

application.

Problem Description Records Format

Offset

Type Field Dec Hex

0 0 BINARY(4) Key

4 4 CHAR(*) Problem record description

Field Descriptions

Key Identifies a particular problem symptom or data. See “Keys” for a list of the possible keys.

Problem record description This describes a particular symptom of the problem, or specifies data to

collect. See “Formats of Specific Problem Description Records” on page 57 for the various problem record

description formats.

Keys

The following table lists the valid keys of the key field area of the software problem record.

Key Description

100 “Key 100-Call Stack Counter” on page 57

101 “Key 101-Suspected Program” on page 57

102 “Key 102-Suspected Service Program” on page 57

103 “Key 103-Suspected Module” on page 58

104 “Key 104-Suspected Procedure” on page 58

105 “Key 105-Detecting Program” on page 58

106 “Key 106-Detecting Service Program” on page 59

107 “Key 107-Problem log entry creation” on page 59

200 “Key 200-Symptom” on page 59


Key Description

201 “Key 201-Instruction Number” on page 60

300 “Key 300-System Object” on page 60

301 “Key 301-Data” on page 60

302 “Key 302-Named System Object” on page 61

303 “Key 303-Spooled File” on page 61

304 “Key 304-Named Integrated File System Object” on page 61

400 “Key 400-Service Identifier” on page 62

Formats of Specific Problem Description Records

Key 100-Call Stack Counter

This key specifies which invocation on the program stack is suspected of causing the error being

reported. If this key is used, you must not use keys 101, 102, 103, or 104. If neither key 100, 101, nor 102

are specified, the API assumes that the program or service program that called the API is the one that has

the problem.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key

4 4 BINARY(4) Call stack counter

Key 101-Suspected Program

This key is used to identify which program is suspected of causing the error being reported. If this key is

used, you must not use key 100 or 102, but should use keys 103 and 104 if applicable. If neither key 100,

101, nor 102 are specified, the API assumes that the program or service program that called the API is the

one that has the problem.

Note: The program must exist on the system at the time the API is called.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key

4 4 BINARY(4) Length of program name

8 8 BINARY(4) Length of library name

12 C CHAR(4) Reserved

16 10 POINTER Program name

32 20 POINTER Library name

Key 102-Suspected Service Program

This key is used to identify which service program is suspected of causing the error being reported. If

this key is used, you must not use key 100 or 101, but should use keys 103 and 104 if applicable. If

neither key 100, 101, nor 102 are specified, the API assumes that the program or service program that

called the API is the one that has the problem.


Note: The service program must exist on the system at the time the API is called.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key

4 4 BINARY(4) Length of service program name



16 10 POINTER Service program name


Key 103-Suspected Module

This key is used to identify which module is suspected of causing the error being reported. If this key is

used, you must not use key 100, but should use keys 101 or 102.

Note: The module must exist on the system at the time the API is called.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key

4 4 BINARY(4) Length of module name



16 10 POINTER Module name


Key 104-Suspected Procedure

This key is used to identify which procedure is suspected of causing the error being reported. If this key

is used, you must not use key 100, but should use key 103 and either 101 or 102.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key

4 4 BINARY(4) Length of procedure name

8 8 CHAR(8) Reserved

16 10 POINTER Procedure name

Key 105-Detecting Program

This key identifies the program that detected the problem. If this key is used, you must not use key 106.

If neither key 105 nor 106 is specified, the API assumes that the program or service program that called

the API is the one that detected the problem.

Note: The program must exist on the system at the time the API is called.


Offset

Type Field Dec Hex

0 0 BINARY(4) Key

4 4 BINARY(4) Length of program name



16 10 POINTER Program name


Key 106-Detecting Service Program

This key identifies the service program that detected the problem. If this key is used, you must not use

key 105. If neither key 105 nor 106 is specified, the API assumes that the program or service program that

called the API is the one that detected the problem.

Note: The service program must exist on the system at the time the API is called.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key

4 4 BINARY(4) Length of service program name



16 10 POINTER Service program name


Key 107-Problem log entry creation

This key identifies whether a problem log entry is created or not. The valid values are ’0’ Unconditional

(problem log entry created) and ’1’ Conditional (problem log entry not created). The default value is ’0’

Unconditional.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key

4 4 CHAR(1) Problem log entry creation

Key 200-Symptom

This key identifies the symptoms associated with the problem. Together, the symptoms form a symptom

string. i5/OS searches for a PTF that has a solution string that matches this symptom string.


Offset

Type Field Dec Hex

0 0 BINARY(4) Key

4 4 BINARY(4) Length of symptom keyword

8 8 BINARY(4) Length of symptom data

12 C CHAR(1) Type of symptom data

13 D CHAR(3) Reserved

16 10 POINTER Pointer to symptom keyword

32 20 POINTER Pointer to symptom data

Key 201-Instruction Number

This key identifies the instruction number where the problem occurred.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key

4 4 CHAR(4) Instruction number

Key 300-System Object

This key identifies system objects associated with the problem. The system objects will be dumped to

spooled files. The spooled files will be kept on an output queue in the APAR library associated with the

problem log entry. You can display the spooled files using the WRKPRB command. The combination of

this key and the other keys related to objects may be specified up to 32 times.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key


16 10 PTR(SYP) Pointer to object

Key 301-Data

This key identifies data associated with the problem. The data is dumped to spooled files. This key may

be specified up to 32 times. The spooled files are kept on an output queue in the APAR library associated

with the problem log entry. You can display the spooled files using the WRKPRB command. The first one

thousand bytes from the list of data items are also sent to the service provider if the problem is reported

and if the “send data packet” flag in the service attributes is on. That data resides in a file named

QAPDFCDP in the APAR library associated with the problem log entry on the service provider.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key

4 4 BINARY(4) Data length

8 8 BINARY(4) Data ID



Offset

Type Field Dec Hex

16 10 POINTER Pointer to data

Key 302-Named System Object

This key names system objects associated with the problem. The system objects will be dumped to

spooled files. The spooled files will be kept on an output queue in the APAR library associated with the

problem log entry. You can display the spooled files using the WRKPRB command. The combination of

this key and the other keys related to objects may be specified up to 32 times.

Note: The object must exist on the system at the time the API is called.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key

4 4 CHAR(30) Object name

34 22 CHAR(30) Object library

64 40 CHAR(10) Object type

Key 303-Spooled File

This key identifies spooled files associated with the problem. The job that created the spooled files must

be the current job. This key may be specified up to 32 times. The spooled files are kept on an output

queue in the APAR library associated with the problem log entry.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key

4 4 CHAR(10) Spooled file name

14 E BINARY(4) Spooled file number

Key 304-Named Integrated File System Object

This key names integrated file system objects associated with the problem. The integrated file system

objects will be dumped to spooled files. The spooled files will be kept on an output queue in the APAR

library associated with the problem log entry. You can display the spooled files using the WRKPRB

command. The combination of this key and the other keys related to objects may be specified up to 32

times.

Notes:

1. The object must exist on the system at the time the API is called.

2. Both absolute and relative path names are allowed. The patterns ? and * are not allowed. The home

directory of the user is not resolved, thus a tilde (~) in the first character position is not treated as the

home directory. The NLS-enabled path name structure (defined in the QLG header file) can be filled

in to specify the coded character set identifier (CCSID) the path name is in.


Offset

Type Field Dec Hex

0 0 BINARY(4) Key


16 10 POINTER NLS-enabled path name structure

Key 400-Service Identifier

This key identifies where in a particular program or service program the problem was reported. The

default service identifier is 9000.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key

4 4 CHAR(4) Service identifier

Field Descriptions

Call stack counter. The number of invocations in the program stack to count from the invocation of the

program or service program that called the API, to the invocation of the program or service program that

is suspected of having the problem. Use 1, for instance, to specify the program or service program that

called the program or service program that called the API. If the call stack counter value exceeds the

number of invocations currently on the program stack, the API uses the invocation of the program or

service program that called the API.

Data ID. This number is used to identify the data that is dumped.

Data length. The length of the data that is dumped.

Instruction number. Specifies exactly where the problem occurred within the specified program or

service program.

Key. Identifies the problem description record.

Length of library name. The length of the library name. The value ranges from 1 to 10.

Length of module name. The length of the module name. The value ranges from 1 to 10.

Length of procedure name. The length of the procedure name. The value ranges from 1 to 256.

Length of program name. The length of the program name. The value ranges from 1 to 10.

Length of service program name. The length of the service program name. The value ranges from 1 to

10.

Length of symptom data. This indicates how many bytes the stored data occupies. The valid range is 1

to 15. The length of the symptom data plus the length of the symptom keyword must not exceed 15.

Length of symptom keyword. The length of the symptom keyword. The valid range is 1 to 15. The

length of the symptom data plus the length of the symptom keyword must not exceed 15.


Library name. A pointer to the name of the library which contains the program, service program, or

module in which the error has occurred.

Module name. A pointer to the name of the module in which the error has occurred.

NLS-enabled path name structure. For more information on this structure, see Path name format.

Object library. The library in which the object resides.

Valid values for the library name are:

*CURLIB The job’s current library.

*LIBL The library list.

library name The specific library that contains the object.

Object name. The name of the object to be dumped.

Object type. The type of object. For a complete list of the available object types, see the Control language

topic collection.

Pointer to data. A space pointer to the data.

Pointer to object. A system pointer to a system object.

Pointer to symptom data. A pointer to the symptom data. The symptom data is a symptom of the

problem. It is concatenated to the symptom keyword. The sum of the symptom keyword length and the

symptom data length must not be longer than 15 characters.

Pointer to symptom keyword. A pointer to the system keyword. The symptom keyword is concatenated

to the symptom data. The sum of the symptom keyword length and the symptom data length must not

be longer than 15 characters. There are a limited number of keywords that can be used. The valid

keywords are:

Table 1. Symptom string keywords

Key Description

(blanks) Normally, a symptom in the symptom string consists of a keyword and data. However, for

flexibility, you may specify a symptom without a keyword.

MSG This is a message identifier associated with the problem.

RC The point of failure is a number that identifies a subroutine, block of code, or specific statement

associated with the problem. Note: This number should not be an instruction number, since the

instruction number may be different for different versions of the same program.

FLDS/ This is the name of a field associated with the problem. It may be followed by the VALU/

keyword to show what value the field contained at the time of the failure.

MOD/ MOD/ is the name of the ILE module that might have caused the problem being reported.

OPCS/ OPCS/ is the name of the command, macro, or instruction associated with the problem.

PCSS/ PCSS/ is a program label that shows generally where the problem occurred.

PRCS/ PRCS/ is a reason code or return code associated with the problem.

REGS/ This is the name of a register associated with the problem. It may be followed by the VALU/

keyword to show what value the register contained at the time of the failure.

RIDS/ RIDS/ is the name of the subroutine or the identifier of the thread in which the problem

occurred.


Key Description

VALU/ VALU/ is the value of a field or register at the time the problem occurred. VALU/ must appear

after key FLDS/ or REGS/.

Procedure name. A space pointer to the name of the procedure in which the error has occurred.

Program name. A pointer to the name of the program in which the error is suspected. The suspected

program name is included in the symptom string (as F/name) created when this API is called. If neither

the 100, 101, nor the 102 keys are used, then the program name in the symptom string defaults to the

caller of this API.

Problem log entry creation. Identifies whether a problem log entry is generated or not. The valid

values are ’0’ Unconditional (problem log entry created) and ’1’ Conditional (problem log entry not

created). The default value is ’0’ Unconditional.

Reserved. Null.

Service identifier. Identifiers where in a program or service program the problem was reported. The

valid range is 1 to 8999.

Service program name. A pointer to the name of the service program in which the error is suspected.

The suspected service program name is included in the symptom string (as F/name) created when this

API is called. If the 100, 101, or the 102 keys are not used, then the service program name in the

symptom string defaults to the caller of this API.

Spooled file name. The name of a spooled file associated with the problem.

Spooled file number. The unique number of a spooled file associated with the problem. The valid range

is 1 through 999999.

The following special values are supported for this parameter:

0 Only one spooled file from the job has the specified file name, so the number of the spooled file is not

necessary.

-1 This uses the highest numbered spooled file with the specified file name.

Type of symptom data. This indicates how the data is stored.


C The data is in displayable form. It must not include blanks or characters that are not displayable.

X The data is in hexadecimal form. The API converts it to displayable characters.

Note:The length of symptom data is the number of bytes used to store the hexadecimal value.

D The data is in zoned decimal form.

P The data is in packed decimal form. The API converts it to displayable numbers.

B The data is in binary form. The API converts it to displayable numbers.

Note:The length of symptom data can only be 2 or 4 bytes if the type of symptom data is B.

Usage Notes

When this API runs within a threaded job, the dump is done of the current thread job.


Error Messages






CPF3C85 D Value for key &1 not allowed with value for key &2.

CPF93C2 D &1 is not a valid number of data items.

CPF93C3 D &1 is not a valid number of object names.

CPF93C8 D Not a valid number of symptoms.

CPF93C9 D Not a valid number of spooled files.

CPF93C0 E Software error logging not active.

CPF93C4 E Error already logged.

CPF93C6 E Suspected program cannot be determined.

CPF93C7E Error in parameter &1.


CPI93B2 I Software problem data for &4 has been detected.



Retrieve Problem Log Entry (QsxRetrieveProblemLogEntry) API





4 Receiver variable Output Char(*)

5 Length of receiver variable Input Binary(4)

6 Return information Output Char(16)

7 Pointer to array of pointers to the keys returned in the

buffer receiver variable

Output PTR(SPP)



The Retrieve Problem Log Entry (QsxRetrieveProblemLogEntry) API allows a user to extract data from a

specific problem log entry, which the caller identifies. The problem log entry is identified by key 1

(problem log ID). The data to be retrieved is identified by the keys passed by reference. The keys used to

identify the data to be retrieved are not changed by the API.

Data is returned in the receiver variable. If you are supplying an automatically extendable space, specify

-1 for the size of the receiver variable. You provide the size and location of this receiver variable. If the

receiver variable is not large enough to contain all the keys requested, the keys successfully retrieved to

that point are returned. The number of keys returned is set in the return information parameter (number

6).

The API can be used to:

v Read a specific key from a problem log entry

v Read a group of keys


#TOP_OF_PAGE

aplist.htm


QSXSRVPL authority

*USE


*USE


Handle

INPUT; BINARY(4)



Key structures


List of keys defining the data to be returned.

Number of keys

INPUT; BINARY(4)

Number of keys passed to the API in the input key array.

Receiver variable

OUTPUT; CHAR(*)

The variable that provides the output buffer.


INPUT; BINARY(4)

The size of the output buffer. If it is -1, an automatically extendable space is assumed.

Return information

OUTPUT; CHAR(16)

v Bytes returned—BINARY(4)

v Bytes available—BINARY(4)

v Number of keys returned—BINARY(4)

v Reserved—BINARY(4)

Pointer to array of pointers to the keys returned in the buffer receiver variable

OUTPUT; PTR(SPP)

The pointer to the array of pointers to the keys returned in the buffer.

Error code

I/O; CHAR(*)


parameter.

Format of the Key Groups

For details about the keys that can be used, see “Key Groups for Problem Log APIs” on page 167.

Rules for Key Usage

Any amount and type of data can be retrieved from the problem log. The limiting factor is the size of the

buffer that is available. The data is returned in a buffer up to the size of the buffer.


Data to be retrieved must be identified by the keys provided. Key 1 (problem log ID) is required. All

other keys are optional, but only data for valid keys defined is returned.

Data, including PTF entries, can be returned individually or in groups. Data that will be returned as a

group are:

v FRU entries

v Text entries

v Supporting data entries

v History entries

Retrieve PTF records

PTF data can be retrieved individually or as a group.

To retrieve all PTFs, use key 7000 (PTF entry). Key 7000 is returned and the count field states how many

Key 7001 (PTF ID) keys are returned. For key 7001, the data required includes PTF ID, product ID,

version, release, and modification level.

To retrieve individual PTFs, use key 7001 (PTF ID) and add the fields that are to be used as the key. Key

1 (problem log ID) and key 7001 (PTF ID) are required. Product data is optional, but can be required if

multiple PTFs have the same PTF identifier.

Retrieve FRU records

To retrieve a FRU group, provide key 2000 (class of FRU entries) and a class. Key 2000 (class of FRU

entries) is returned with a count of FRU entries and 2000—2009 are returned.

Retrieve text records

To retrieve the text data, provide key 3000 (text entry) and the text type. Key 3000 (text entry) is returned

with a count of key 3001 (text entry) returned. Only one is returned unless all text was requested.

Retrieve supporting data

To retrieve supporting data records, provide key group 4000 (supporting data entries) and the type. Key

group 4000 is returned with a count of the entries and key 4001 (spooled file data) and 4002 are returned.

Retrieve history records

To retrieve the history data, provide key 6000 (history information) and specify last or all. Key 6000

(history information) is returned with a count of the history entries and key 6001 (history information) is

returned.

Retrieve analyzed error flag:

To retrieve the analyzed eror flag data, provide key 8000 (analyzed error flag entries). Key 8000 returns a

value that indicates whether the problem has been analyzed by System Licensed Internal Code (SLIC).

Retrieve logical partition ID:

To retrieve the logical partition ID data, provide key 9000 (logical partition ID). Key 9000 returns the

current logical partition ID on the physical machine.

Error Messages













CPD7A84 D Buffer area not accessible.









Start Problem Log Services (QsxStartProblemLogServices) API


1 Handle Output Binary(4)



The Start Problem Log Services (QsxStartProblemLogServices) API sets up the environment to allow

creating, changing, deleting, and retrieving problem log entries. The procedure performs the following

functions:

v Opens the problem log files for update.

v Starts commitment control

v Returns a handle that must be supplied as a parameter by the using problem log APIs.

Only one instance of the problem log services may be started from a job. Attempting to start multiple

instances of the problem log services will result in an error. Attempting to use one of the problem log

APIs without the proper handle will also result in an error.



*USE

Required Parameter

Handle

OUTPUT; BINARY(4)

This provides a means of associating the problem log services that are started with subsequent

problem log activities that will be performed.

Error code

I/O; CHAR(*)


#TOP_OF_PAGE

aplist.htm


parameter.

Error Messages






CPF7A86 E Problem log services already started.






Work with Problem (QPDWRKPB) API


1 Display panels Input Char(10)

2 Problem ID number Input Char(10)

3 Origin system Input Char(20)

4 Current problem status Input Char(10)

5 Requested problem statuses Input Array of Char(10)

6 Number of requested problem statuses Input Binary(4)

7 Service provider network identifier Input Char(8)

8 Service provider control point name Input Char(8)

9 Problem severity Input Char(1)


Optional Parameter Group:

11 Note text Input Char(*)

12 Length of note text Input Binary(4)

Default Public Authority: *USE Threadsafe: No

The Work with Problem (QPDWRKPB) API uses a problem log entry to analyze and prepare a

machine-detected hardware problem for reporting. Only local machine-detected problems that have an

OPEN, READY, PREPARED, or SENT status can be analyzed and prepared for reporting. Remote

problems that have an OPEN, READY, PREPARED, or SENT status can be prepared for reporting but

cannot be analyzed. This API does not analyze or prepare user-detected problems.

If a machine-detected problem is analyzed, the problem analysis program associated with the problem is

called to generate a problem analysis list identifying all the possible causes for the problem.


None.


#TOP_OF_PAGE

aplist.htm


Display panels

INPUT; CHAR(10)

Whether or not displays are shown during problem analysis. Valid values are:

*NO No displays are shown.

Note: During problem analysis, if displays are usually shown for the type of hardware associated

with the problem, then the Point of Failure list is saved. This list is only saved if no other list of

causes currently associated with the problem exists.

*YES All displays are shown. This value is not allowed if the API is called in a batch job.

Problem ID number

INPUT; CHAR(10)

The number the system generates to identify a problem.

Origin system

INPUT; CHAR(20)

The node name of the origin system (the format is network-ID.control-point-name).

Current problem status

INPUT; CHAR(10)

The current status of the problem. If the problem is found to be in a status other than what is

indicated, an error occurs. Valid values are:

*OPENED The problem was identified and a problem record was created.

*READY Problem analysis information has been added to the problem record.

*PREPARED The problem has been prepared for reporting.

*SENT The problem record was sent to a service provider, and the information needed to correct the

problem was not returned.

*ANSWERED The problem has been answered.

Requested problem statuses

INPUT; ARRAY of CHAR(10)

The requested status for the problem.

Valid values are:

*READY Analyze the problem. Valid for local machine-detected problems only.

*PREPARED Prepare the problem for reporting. The service provider network identifier, service provider

control point name, and problem severity parameters and the default contact database are used.

Note: If you select *READY and *PREPARED, the final status is *PREPARED.

Number of requested problem statuses

INPUT; BINARY(4)

The number of statuses entered for requested problem statuses parameter.

Service provider network identifier

INPUT; CHAR(8)

The network identifier of the service provider system where the problem is to be sent.

Valid values are:

*NETATR The network identifier of this system. Use *NETATR if the control point name is *IBMSRV.


Service provider control point name

INPUT; CHAR(8)

The control point name of the service provider system where the problem is to be sent.

Valid values are:

*IBMSRV IBM®

service support. This value cannot be used if the problem has an *OPENED status unless

you also have a requested problem status of *READY.

Name The control point name.

Problem severity

INPUT; CHAR(1)

The severity of the problem.

Valid values are:

1 A high severity level in which there is a critical affect on operations. A severity 1 problem requires a service

representative at the site, and the person solving the problem must work on the problem 24 hours a day until

the problem is solved or circumvented. If the problem needs more information, patching, or the problem must

be created again on the failing system, a service representative must be available to do these tasks

immediately. It is not a severity 1 if these and any other tasks cannot be performed immediately.

2 A medium severity level in which you are able to use the system, but your operations are severely restricted

by the problem.

3 A low severity level in which you are able to continue operations with some restrictions. The restrictions do

not have a critical effect on your operations.

4 The severity level is minimal because the problem causes little or no effect to your operation, or you have

found a way to circumvent the problem.

Error code

I/O; CHAR(*)


parameter.

Optional Parameter Group

Note text

INPUT; CHAR(*)

The field used to include a note stating that a problem originated with the service director. The

note will be included when the API is called.

Length of note text

INPUT; BINARY(4)

The length of the text for the note text field. The text field for the note text field can be up to 80

characters long.

Error Messages






CPF7A9C E Cannot work with the problem log at this time.

CPF7A9D E Problem log object &1 is missing.

CPF7A93 E Problem &2 currently in use by job &1.



CPF8C09 E &1 not defined as a service provider.

CPF8C24 E Error occurred while processing request.

CPF8C87 E Service provider &1.&2 not found.

CPF9308 E Unable to complete problem analysis. Reason code &1.

CPF931C E Problem analysis results not recorded in problem log.

CPF9310 E Problem analysis procedure was exited before it had completed.

CPF9313 E Requested procedure is not allowed.

CPF932A E Number of requested statuses is not valid.

CPF932B E *IBMSRV not allowed as service provider for problems in OPENED status.

CPF9320 E &1 to display panels is not valid.

CPF9321 E Panels cannot be displayed in a batch job.

CPF9322 E Current status &3 does not match problem status &4.

CPF9323 E Current status &1 is not valid.

CPF9324 E Problems on a remote system cannot be analyzed.

CPF9325 E Problem &1 has a status that is not allowed.

CPF9326 E Problem selected not allowed.

CPF9327 E Problem analysis procedure was exited before it had completed.

CPF9328 E Severity &1 is not valid.

CPF9329 E Requested status &1 is not valid.

CPF7845 E Error occurred while opening file &1.

CPF7846 E Error while processing file &1 in library &2.

CPF7847 E Error occurred while closing file &1 in library &2.




QTRC Trace APIs

The QTRC Trace APIs provide support for writing application trace data. Using these APIs, you can do

the following tasks:

v Retrieve the current active trace level for a component.

v Write component trace data as a string of text, hexadecimal dump, or call stack.

The QTRC Trace APIs provide support for application developers to enable their programs for tracing, on

a component-by-component basis. Components operate independently of one another. Each component

trace point is further categorized by a trace level, and can optionally define a subcomponent and function

name.

For additional information about the QTRC Trace environment, see the following topics:

v “QTRC Trace Definitions” on page 211

v “QTRC Trace Levels” on page 214

v “QTRC Trace Data Collected” on page 214

v “QTRC Trace Collecting a Component Trace” on page 216

v “QTRC Trace Tips” on page 217

The QTRC Trace APIs include:

v

“QtrcGetActiveLevel()—Get Active Trace Level” on page 73 (QtrcGetActiveLevel()) retrieves the

active trace level for the specified component.

v

“QtrcWriteStack()—Write Call Stack Trace Data” on page 76 (QtrcWriteStack()) writes a component

trace record as call stack data to an active trace collection if certain trace conditions are met.


#TOP_OF_PAGE

aplist.htm

v

“QtrcWriteHexDumpF()—Write Hexadecimal Dump Formatted Trace Data” on page 79

(QtrcWriteHexDumpF()) writes a component trace record as hexadecimal dump data to an active trace

collection if certain trace conditions are met. Format options can be used to indicate the desired

formatting of the hexadecimal dump.

v

“QtrcWriteHexDump()—Write Hexadecimal Dump Trace Data” on page 83 (QtrcWriteHexDump())

writes a component trace record as hexadecimal dump data to an active trace collection if certain trace

conditions are met.

v

“QtrcWriteText()—Write Text Trace Data” on page 86 (QtrcWriteText()) writes a component trace

record as text string data to an active trace collection if certain trace conditions are met.

v

“QtrcWriteTextPPrintF()—Write Text Trace Data Using Pointer-based Print Formatted” on page 89

(QtrcWriteTextPPrintF()) writes a component trace record as text string data, using a pointer-based

print formatted layout, to an active trace collection if certain trace conditions are met.

v

“QtrcWriteTextPrintF()—Write Text Trace Data Using Print Formatted” on page 94

(QtrcWriteTextPrintF()) writes a component trace record as text string data, using a print formatted

layout, to an active trace collection if certain trace conditions are met.

v

“QtrcWriteTextVPrintF()—Write Text Trace Data Using Variable Argument List Print Formatted” on

page 98 (QtrcWriteTextVPrintF()) writes a component trace record as text string data, using a variable

argument list print formatted layout, to an active trace collection if certain trace conditions are met.


QtrcGetActiveLevel()—Get Active Trace Level

Syntax #include <qtrc.h>

int QtrcGetActiveLevel

(const char *Component,

unsigned int *Active_Level);

Service Program Name: QTRCMGR Default Public Authority: *USE Threadsafe: Yes

The QtrcGetActiveLevel() function retrieves the active trace level for the specified Component and places

the result into the integer pointed to by Active_Level.

A successful call to the QtrcGetActiveLevel() function results in one of the following values for the

Active_Level:

QTRC_LEVEL_NONE (0) Trace is not active for the specified Component.

QTRC_LEVEL_ERROR (1) Trace level ERROR is active for the specified Component.

QTRC_LEVEL_INFO (2) Trace level INFO is active for the specified Component.

QTRC_LEVEL_VERBOSE (3) Trace level VERBOSE is active for the specified Component.

If the specified Component is not defined to a trace collection, the Active_Level value is set to

QTRC_LEVEL_NONE (0). Components are defined to a trace collection using the Start Trace (STRTRC) CL

command.


#TOP_OF_PAGE

aplist.htm

Parameters

Component

(Input)

A pointer to the null-terminated component name. The component name should be 10 characters

in length or less. If more than 10 characters are specified, only the first 10 characters are used.

Active_Level

(Output)

A pointer to the integer variable to receive the active trace level value.


None.

Return Value

0 QtrcGetActiveLevel() was successful.

value QtrcGetActiveLevel() was not successful. value is set to indicate the error condition.

Error Conditions

If QtrcGetActiveLevel() was not successful, the error condition returned usually indicates one of the

following errors. Under some conditions, the value returned could indicate an error other than those

listed here.

Error condition Additional information

[EINVAL (page 222)] The specified Component is not a valid component name.

[EFAULT (page 223)]

[EUNKNOWN (page 226)]

Error Messages

None.

Usage Notes

1. The main purpose for using the QtrcGetActiveLevel() is to determine if the specified Component has

been used on the Start Trace (STRTRC) CL command, for the Trace type (TRCTYPE) parameter. If the

component and its trace level were used on STRTRC, the Active_Level returned by QtrcGetActiveLevel

will reflect the trace level value that was used (*ERROR, *INFO, or *VERBOSE). If not, the Active_Level

will indicate a trace level value of QTRC_LEVEL_NONE (0), which means trace is not currently active

for the specified Component.

2. Using the QtrcGetActiveLevel() function may have a slight performance impact if called often, even

when component tracing is not currently active. To help alleviate such performance impacts, the

QtrcGetActiveLevel() function should be called sparingly, and the results saved into a variable for

later use throughout a program or function call. The variable should be periodically updated, to

ensure a current view of the component’s active trace level. For example, the variable should be

updated using the QtrcGetActiveLevel() function in the following conditions:

v Upon entry to a program or major function.

v After coming out of a wait.

v After calling a long-running program or function.

v After each iteration of a major loop cycle.


Related Information

v “QtrcWriteHexDump()—Write Hexadecimal Dump Trace Data” on page 83—Write Hexadecimal Dump

Trace Data

v “QtrcWriteHexDumpF()—Write Hexadecimal Dump Formatted Trace Data” on page 79—Write

Hexadecimal Dump Formatted Trace Data

v “QtrcWriteStack()—Write Call Stack Trace Data” on page 76—Write Call Stack Trace Data

v “QtrcWriteText()—Write Text Trace Data” on page 86—Write Text Trace Data

v “QtrcWriteTextPrintF()—Write Text Trace Data Using Print Formatted” on page 94—Write Text Trace

Data using Print Formatted

v “QtrcWriteTextPPrintF()—Write Text Trace Data Using Pointer-based Print Formatted” on page

89—Write Text Trace Data using Pointer-based Print Formatted

v “QtrcWriteTextVPrintF()—Write Text Trace Data Using Variable Argument List Print Formatted” on

page 98—Write Text Trace Data using Variable Argument List Print Formatted

v Start Trace (STRTRC) CL command

v For additional information about the QTRC Trace environment, see “QTRC Trace APIs” on page 72.

Example

The following example retrieves the active trace level for a component named MYCOMP. The example

output assumes the Start Trace (STRTRC) CL command was used before calling the example, specifying

TRCTYPE((MYCOMP *INFO)).



#include <qtrc.h>

#include <stdio.h>

#include <errno.h>

int main(int argc, char *argv[])

{

unsigned int myCompActLvl = QTRC_LEVEL_NONE;

const char *myComp = "MYCOMP";

int rc;

rc = QtrcGetActiveLevel(myComp, &myCompActLvl);

if (rc != 0) {

printf("QtrcGetActiveLevel() failed with error %d\n",

rc);

return -1;

}

printf("%s active trace level is: ",myComp);

switch (myCompActLvl) {

case QTRC_LEVEL_NONE:

printf("NONE\n");

break;

case QTRC_LEVEL_ERROR:

printf("ERROR\n");

break;

case QTRC_LEVEL_INFO:

printf("INFO\n");

break;

case QTRC_LEVEL_VERBOSE:

printf("VERBOSE\n");

break;

}

return 0;

}


Example Output:

MYCOMP active trace level is: INFO



QtrcWriteStack()—Write Call Stack Trace Data


int QtrcWriteStack

(unsigned int Coded_Level,

const char *Component,

const char *Subcomponent,

const char *Function,

const char *Label);


The QtrcWriteStack() function writes a component trace record as call stack data to an active trace

collection if certain trace conditions are met.

Each call to the QtrcWriteStack() function is considered a trace point. A component trace record is written

to the trace collection when all the trace conditions are met for a given trace point. The trace conditions

include:

v A trace collection must be active for the current thread.

v The specified Component must be part of the trace collection.

v The active trace level that was used for the specified Component when the trace collection was started

must allow the Coded_Level of the trace point.

Each trace point must indicate the desired trace level using the Coded_Level parameter. This trace level is

compared against the active trace level that was used for the specified Component when the trace

collection was started. Components are defined to the trace collection using the Start Trace (STRTRC) CL

command. The Coded_Level must be one of the following values:

QTRC_LEVEL_ERROR (1) ERROR-level trace point. A component trace record is written if the Component

has an active trace level of either *ERROR, *INFO, or *VERBOSE.

QTRC_LEVEL_INFO (2) INFO-level trace point. A component trace record is written if the Component has

an active trace level of either *INFO or *VERBOSE.

QTRC_LEVEL_VERBOSE (3) VERBOSE-level trace point. A component trace record is written if the Component

has an active trace level of *VERBOSE.

Parameters

Coded_Level

(Input)

The trace level of the trace point.

Component

(Input)


#TOP_OF_PAGE

aplist.htm



Subcomponent

(Input)

A pointer to the null-terminated subcomponent name. The subcomponent name should be 10

characters in length or less. If more than 10 characters are specified, only the first 10 characters

are used. This parameter can be set to NULL if no subcomponent is to be defined.

Function

(Input)

A pointer to the null-terminated function name. The function name should be 512 characters in

length or less. If more than 512 characters are specified, only the first 512 characters are used.

This parameter can be set to NULL if no function is to be defined.

Label (Input)

A pointer to the null-terminated label that will precede the call stack data. The label should be

128 characters in length or less. If more than 128 characters are specified, only the first 128

characters are used. This parameter can be set to NULL if no label is to be defined.


None.

Return Value

0 QtrcWriteStack() was successful. However, the component trace record will only be written if the

trace conditions are met.

value QtrcWriteStack() was not successful. An error condition was detected which would prevent the

component trace record from ever being written.

Error Conditions

If QtrcWriteStack() was not successful, the error condition returned usually indicates one of the following

errors. Under some conditions, the value returned could indicate an error other than those listed here.


[EINVAL (page 222)] The specified Coded_Level is not one of the supported trace levels.

The specified Component is not a valid component name.

[EFAULT (page 223)]


Error Messages

None.

Usage Notes

1. If the QtrcWriteStack() function is called multiple times, there may be a noticeable performance

impact. The “QtrcGetActiveLevel()—Get Active Trace Level” on page 73 API can be used, and the

results saved into a variable for later, multiple uses. The variable can be used to quickly check if the

specified Component is currently active at the appropriate trace level, prior to calling the

QtrcWriteStack() function. The variable should be periodically updated, to ensure a current view of

the component’s active trace level. Refer to the “QTRC Trace APIs” on page 72 for additional

information concerning the use of trace levels.


2. Refer to the “QTRC Trace APIs” on page 72 for additional information concerning the Coded_Level,

Component, Subcomponent, Function, and Label parameters.

Related Information

v “QtrcGetActiveLevel()—Get Active Trace Level” on page 73—Get Active Trace Level


Trace Data


Hexadecimal Dump Trace Formatted Data










Example

The following example uses an INFO-level trace point to write call stack trace data for a component

named MYCOMP. The component trace record will be written to the active trace collection if the STRTRC

CL command was used before calling the example, specifying either TRCTYPE((MYCOMP *INFO)) or

TRCTYPE((MYCOMP *VERBOSE)).



#include <qtrc.h>

#include <stdio.h>

#include <errno.h>


{


int rc;

rc = QtrcWriteStack(QTRC_LEVEL_INFO,

myComp,

"SUBCOMP",

argv[0],

"Call stack shows how we got here" );

if (rc != 0) {

printf("QtrcWriteStack() failed with error %d\n",

rc);

return -1;

}

printf("Use the ENDTRC CL command with PRTTRC(*YES) in order to\n");

printf("see the component trace records that were written to the\n");

printf("trace collection.\n");

return 0;

}

Example Output:


Use the ENDTRC CL command with PRTTRC(*YES) in order to

see the component trace records that were written to the

trace collection.



QtrcWriteHexDumpF()—Write Hexadecimal Dump Formatted Trace Data


int QtrcWriteHexDumpF





const char *Label,

const void *Data,

size_t Data_Length,

unsigned int Format_Option,

void *Reserved);


The QtrcWriteHexDumpF() function writes a component trace record as hexadecimal dump data to an

active trace collection if certain trace conditions are met. A format option can be used to indicate the

desired formatting of the hexadecimal dump through the Format_Option parameter.

Each call to the QtrcWriteHexDumpF() function is considered a trace point. A component trace record is

written to the trace collection when all the trace conditions are met for a given trace point. The trace

conditions include:















Parameters

Coded_Level

(Input)


#TOP_OF_PAGE

aplist.htm


Component

(Input)



Subcomponent

(Input)




Function

(Input)




Label (Input)

A pointer to the null-terminated label that will precede the hexadecimal dump data. The label

should be 128 characters in length or less. If more than 128 characters are specified, only the first

128 characters are used. This parameter can be set to NULL if no label is to be defined.

Data (Input)

A pointer to the data to be written as a hexadecimal dump.

Data_Length

(Input)

The length in bytes of the data to be written.

Format_Option

(Input)

The desired formatting option to be used for the hexadecimal dump. The formatting option must

be set to one of the following:

QTRC_FORMAT_OPTION_NONE (0) No format. Only the hexadecimal data will be shown in the trace record.

This option is equivalent to using the “QtrcWriteHexDump()—Write

Hexadecimal Dump Trace Data” on page 83 API.

QTRC_FORMAT_OPTION_EBCDIC (1) EBCDIC format. The hexadecimal data will be shown in the trace record

along with the EBCDIC representation of that data.

QTRC_FORMAT_OPTION_ASCII (2) ASCII format. The hexadecimal data will be shown in the trace record

along with the ASCII representation of that data.

QTRC_FORMAT_OPTION_UTF8 (3) UTF-8 format. The hexadecimal data will be shown in the trace record

along with the UTF-8 representation of that data.

QTRC_FORMAT_OPTION_UTF16 (4) UTF-16 format. The hexadecimal data will be shown in the trace record

along with the UTF-16 representation of that data.

Reserved

(Input)

Reserved for future use. Must be set to NULL.


None.


Return Value

0 QtrcWriteHexDumpF() was successful. However, the component trace record will only be written

if the trace conditions are met.

value QtrcWriteHexDumpF() was not successful. An error condition was detected which would prevent

the component trace record from ever being written.

Error Conditions

If QtrcWriteHexDumpF() was not successful, the error condition returned usually indicates one of the


listed here.




The specified Format_Option is not one of the supported formatting options.

The Reserved parameter is not NULL.

[EFAULT (page 223)]


Error Messages

None.

Usage Notes

1. If the QtrcWriteHexDumpF() function is called multiple times, there may be a noticeable performance




QtrcWriteHexDumpF() function. The variable should be periodically updated, to ensure a current

view of the component’s active trace level. Refer to the “QTRC Trace APIs” on page 72 for additional




3. When the Format_Option indicates EBCDIC format, code page 37 is used for the EBCDIC

representation. When the Format_Option indicates ASCII format, code page 819 is used for the ASCII

representation.

Related Information



Trace Data












Example

The following example uses a VERBOSE-level trace point to write EBCDIC formatted hexadecimal dump

trace data for a component named MYCOMP. The component trace record will only be written to the

active trace collection if the STRTRC CL command was used before calling the example, specifying

TRCTYPE((MYCOMP *VERBOSE)).



#include <qtrc.h>

#include <stdio.h>

#include <errno.h>


{


char myBuffer[256];

int i, rc;

for (i=0; i<sizeof(myBuffer); ++i) {

myBuffer[i] = i;

}

rc = QtrcWriteHexDumpF(QTRC_LEVEL_VERBOSE,

myComp,

"SUBCOMP",

argv[0],

"Contents of myBuffer after initialization",

(void *)myBuffer,

sizeof(myBuffer),

QTRC_FORMAT_OPTION_EBCDIC,

NULL );

if (rc != 0) {

printf("QtrcWriteHexDumpF() failed with error %d\n",

rc);

return -1;

}




return 0;

}

Example Output:



trace collection.




#TOP_OF_PAGE

aplist.htm

QtrcWriteHexDump()—Write Hexadecimal Dump Trace Data


int QtrcWriteHexDump





const char *Label,

const void *Data,

size_t Data_Length);


The QtrcWriteHexDump() function writes a component trace record as hexadecimal dump data to an

active trace collection if certain trace conditions are met.

Each call to the QtrcWriteHexDump() function is considered a trace point. A component trace record is


conditions include:















Parameters

Coded_Level

(Input)


Component

(Input)



Subcomponent

(Input)





Function

(Input)




Label (Input)

A pointer to the null-terminated label that will precede the hexadecimal dump data. The label

should be 128 characters in length or less. If more than 128 characters are specified, only the first

128 characters are used. This parameter can be set to NULL if no label is to be defined.

Data (Input)

A pointer to the data to be written as a hexadecimal dump.

Data_Length

(Input)

The length in bytes of the data to be written.


None.

Return Value

0 QtrcWriteHexDump() was successful. However, the component trace record will only be written


value QtrcWriteHexDump() was not successful. An error condition was detected which would prevent


Error Conditions

If QtrcWriteHexDump() was not successful, the error condition returned usually indicates one of the


listed here.




[EFAULT (page 223)]


Error Messages

None.

Usage Notes

1. If the QtrcWriteHexDump() function is called multiple times, there may be a noticeable performance





QtrcWriteHexDump() function. The variable should be periodically updated, to ensure a current view

of the component’s active trace level. Refer to the “QTRC Trace APIs” on page 72 for additional




Related Information














Example

The following example uses INFO-level trace points to write hexadecimal dump trace data for a

component named MYCOMP. The QtrcGetActiveLevel function is used, since there are more than one

trace points, as described in the Performance section of “QTRC Trace Tips” on page 217. The component

trace records will be written to the active trace collection if the STRTRC CL command was used before

calling the example, specifying either TRCTYPE((MYCOMP *INFO)) or TRCTYPE((MYCOMP

*VERBOSE)).



#include <qtrc.h>

#include <stdio.h>

#include <errno.h>

#define BUFFERELEMENTS 256


{


unsigned int myCompActLvl;

char myBuffer[BUFFERELEMENTS];

int myBuffer2[BUFFERELEMENTS];

int i, rc;


if (rc != 0) {

printf("QtrcGetActiveLevel() failed with error %d\n", rc);

return -1;

}

for (i=0; i<BUFFERELEMENTS; ++i) {

myBuffer[i] = i;

}

if (myCompActLvl >= QTRC_LEVEL_INFO) {

rc = QtrcWriteHexDump(QTRC_LEVEL_INFO,


myComp,

"SUBCOMP",

argv[0],

"Contents of myBuffer after initialization",

(void *)myBuffer,

sizeof(myBuffer) );

if (rc != 0) {

printf("QtrcWriteHexDump() myBuffer failed with error %d\n", rc);

return -1;

}

}

for (i=0; i<BUFFERELEMENTS; ++i) {

myBuffer2[i] = i;

}


rc = QtrcWriteHexDump(QTRC_LEVEL_INFO,

myComp,

"SUBCOMP",

argv[0],

"Contents of myBuffer2 after initialization",

(void *)myBuffer2,

sizeof(myBuffer2) );

if (rc != 0) {

printf("QtrcWriteHexDump() myBuffer2 failed with error %d\n", rc);

return -1;

}

}




return 0;

}

Example Output:



trace collection.



QtrcWriteText()—Write Text Trace Data


int QtrcWriteText





const char *Text);



#TOP_OF_PAGE

aplist.htm

The QtrcWriteText() function writes a component trace record as text string data to an active trace

collection if certain trace conditions are met.

Each call to the QtrcWriteText() function is considered a trace point. A component trace record is written

to the trace collection when all the trace conditions are met for a given trace point. The trace conditions

include:















Parameters

Coded_Level

(Input)


Component

(Input)



Subcomponent

(Input)




Function

(Input)




Text (Input)

A pointer to the null-terminated text to be written as trace data. The text should be 2048

characters in length or less. If more than 2048 characters are specified, only the first 2048

characters are used.


None.


Return Value

0 QtrcWriteText() was successful. However, the component trace record will only be written if the

trace conditions are met.

value QtrcWriteText() was not successful. An error condition was detected which would prevent the

component trace record from ever being written.

Error Conditions

If QtrcWriteText() was not successful, the error condition returned usually indicates one of the following

errors. Under some conditions, the value returned could indicate an error other than those listed here.




[EFAULT (page 223)]


Error Messages

None.

Usage Notes

1. If the QtrcWriteText() function is called multiple times, there may be a noticeable performance impact.

The “QtrcGetActiveLevel()—Get Active Trace Level” on page 73 API can be used, and the results

saved into a variable for later, multiple uses. The variable can be used to quickly check if the specified

Component is currently active at the appropriate trace level, prior to calling the QtrcWriteText()

function. The variable should be periodically updated, to ensure a current view of the component’s

active trace level. Refer to the “QTRC Trace APIs” on page 72 for additional information concerning

the use of trace levels.


Component, Subcomponent, and Function parameters.

3. The Text parameter is used to write a string of characters as trace data. This provides a simple way to

write out trace data that describes a state or action. For example, the Text could be something like

″Exit: rc=0″ or ″Entry was removed from linked list.″

4. The Text parameter should only contain characters in the invariant character set.

5. The total amount of text data that can be written as trace data is limited to 2048 characters. In order

to trace more than 2048 characters of text data, the QtrcWriteHexDumpF function could be used to

write the text data as hexadecimal trace data with a formatting option that includes the appropriate

text representation. An alternative would be to split up the text data into multiple sections and call

the QtrcWriteText() function for each section.

Related Information



Trace Data







v “QtrcWriteTextPPrintF()—Write Text Trace Data Using Pointer-based Print Formatted”—Write Text

Trace Data using Pointer-based Print Formatted





Example

The following example uses an ERROR-level trace point to write text trace data for a component named

MYCOMP. The component trace record will be written to the active trace collection if the program is

called with no parameters and the STRTRC CL command was used before calling the example, specifying

either TRCTYPE((MYCOMP *ERROR)), TRCTYPE((MYCOMP *INFO)), or TRCTYPE((MYCOMP

*VERBOSE)).



#include <qtrc.h>

#include <stdio.h>

#include <errno.h>


{


int rc;

if (argc <= 1) {

rc = QtrcWriteText(QTRC_LEVEL_ERROR,

myComp,

"SUBCOMP",

argv[0],

"At least one parm required - return EINVAL." );

if (rc != 0) {

printf("QtrcWriteText() failed with error %d\n", rc);

}




return EINVAL;

}

return 0;

}

Example Output:



trace collection.



QtrcWriteTextPPrintF()—Write Text Trace Data Using Pointer-based

Print Formatted

Syntax


#TOP_OF_PAGE

aplist.htm

#include <qtrc.h>

int QtrcWriteTextPPrintF





const char *Format,

...);


The QtrcWriteTextPPrintF() function writes a component trace record as text string data, using a

pointer-based print formatted layout, to an active trace collection if certain trace conditions are met. Note:

The QtrcWriteTextPPrintF() function is intended to be used only by prototyped call languages, such as

RPG. Other languages, such as C and C++, should instead use the “QtrcWriteTextPrintF()—Write Text

Trace Data Using Print Formatted” on page 94 function.

The QtrcWriteTextPPrintF() uses the Format parameter to process any additional parameters

(Argument_List) that are specified following the Format parameter. The QtrcWriteTextPPrintF() function

works just like the “QtrcWriteTextPrintF()—Write Text Trace Data Using Print Formatted” on page 94

function, except that the additional parameters (Argument_List) are all expected to be pointers (references)

to the entries to be formatted. Format specifications, which begin with a percent sign (%), are used to

convert each corresponding argument list entry referenced by the pointer, and include the resulting text

string in the trace record. If there are more argument list referenced entries than there are format

specifications, the extra arguments are evaluated and ignored. The results are undefined if there are not

enough argument list referenced entries for all the format specifications.

Each call to the QtrcWriteTextPPrintF() function is considered a trace point. A component trace record is


conditions include:















Parameters

Coded_Level

(Input)



Component

(Input)



Subcomponent

(Input)




Function

(Input)




Format

(Input)

A pointer to the null-terminated format string. The format string provides the format specification

of the text to be written as a trace record. See the printf()—Print Formatted Characters function

for a description of valid format strings and how the format specifications are used along with an

argument list.

... (Argument_List)

(Input)

An optional list of arguments that contain pointers (references) to entries that are to be formatted

and written as part of the text string trace record.


None.

Return Value

0 QtrcWriteTextPPrintF() was successful. However, the component trace record will only be written


value QtrcWriteTextPPrintF() was not successful. An error condition was detected which would prevent


Error Conditions

If QtrcWriteTextPPrintF() was not successful, the error condition returned usually indicates one of the


listed here.




[EFAULT (page 223)]



Error Messages

None.

Usage Notes

1. If the QtrcWriteTextPPrintF() function is called multiple times, there may be a noticeable performance




QtrcWriteTextPPrintF() function. The variable should be periodically updated, to ensure a current





3. The Format parameter and the corresponding Argument_List is used to write a string of characters as

trace data, in a style similar to the printf() function. This provides a simple way to write out text trace

data with replacement values. For example, the Format could be something like ″Function myLocator()

returned %d″ and the argument list would be a pointer (reference) to the return code variable myRC

(namely, &myRC), if the function was called with myRC=myLocator(). The Format string is assumed

to be in the CCSID of the job.

4. A single prototype of this function can be declared, such that all the parameters following the Format

parameter are pointers. This Argument_List would contain pointer parameters that correspond to the

Format, and any additional pointer parameters should be specified as NULL.

5. The major difference between the QtrcWriteTextPPrintF() API and the printf() function is that a

pointer (reference) to the data type must be provided in the Argument_List for the various format

types. The format types s, p, and S are already specified as a pointer, in the exact same manner as the

printf() function.

6. The Format parameter supports most of the format specifications, as defined by the printf() function,

as of the release that this QtrcWriteTextPPrintF() function was introduced. Any format specification

added to the printf() function in a subsequent release is not supported, unless specifically indicated

by this documentation. The following format specifications are not supported, and the results are

undefined if they are used:

v The %n$ form, where n is a positive integer constant which represents an argument number.

v The %D(n,p) packed decimal format type.

v The %n pointer to integer format type.

v The %lc wide character format type. Use %C instead.

v The %ls wide character format type. Use %S instead.

v The asterisk (*), used as a width specification.

v The asterisk (*), used as a precision specification.7. The Format parameter should only contain characters in the invariant character set. This is also true

for any strings that may be used in the Argument_List.





the QtrcWriteTextPPrintF() function for each section.

Related Information



Trace Data







Data Using Print Formatted


page 98—Write Text Trace Data Using Variable Argument List Print Formatted

v printf()—Print Formatted Characters



Example

The following example uses an INFO-level trace point to write formatted text trace data for a component

named MYCOMP. The component trace record will be written to the active trace collection if the program

is called with at least one parameter and the STRTRC CL command was used before calling the example,

specifying either TRCTYPE((MYCOMP *INFO)) or TRCTYPE((MYCOMP *VERBOSE)).



#include <qtrc.h>

#include <stdio.h>


{


const int ParmNum = 1;

int rc;

if (argc > 1) {

rc = QtrcWriteTextPPrintF(QTRC_LEVEL_INFO,

myComp,

"SUBCOMP",

argv[0],

"Parameter %d is %s", &ParmNum, argv[ParmNum] );

if (rc != 0) {

printf("QtrcWriteTextPPrintF() failed with error %d\n", rc);

return -1;

}

}




return 0;

}

Example Output:



trace collection.




#TOP_OF_PAGE

aplist.htm

QtrcWriteTextPrintF()—Write Text Trace Data Using Print Formatted


int QtrcWriteTextPrintF





const char *Format,

...);


The QtrcWriteTextPrintF() function writes a component trace record as text string data, using a print

formatted layout, to an active trace collection if certain trace conditions are met. Note: A prototyped call

language, such as RPG, should instead use the “QtrcWriteTextPPrintF()—Write Text Trace Data Using

Pointer-based Print Formatted” on page 89 function.

The QtrcWriteTextPrintF() uses the Format parameter to process any additional parameters

(Argument_List) that are specified following the Format parameter. Format specifications, which begin with

a percent sign (%), are used to convert each corresponding argument list entry, and include the resulting

text string in the trace record. If there are more argument list entries than there are format specifications,

the extra arguments are evaluated and ignored. The results are undefined if there are not enough

argument list entries for all the format specifications.

Each call to the QtrcWriteTextPrintF() function is considered a trace point. A component trace record is


conditions include:















Parameters

Coded_Level

(Input)



Component

(Input)



Subcomponent

(Input)




Function

(Input)




Format

(Input)


of the text to be written as a trace record. See the printf()—Print Formatted Characters function

for a description of valid format strings and how the format specifications are used along with an

argument list.

... (Argument_List)

(Input)

An optional list of arguments that contain entries to be formatted and written as part of the text

string trace record.


None.

Return Value

0 QtrcWriteTextPrintF() was successful. However, the component trace record will only be written


value QtrcWriteTextPrintF() was not successful. An error condition was detected which would prevent


Error Conditions

If QtrcWriteTextPrintF() was not successful, the error condition returned usually indicates one of the


listed here.




[EFAULT (page 223)]



Error Messages

None.

Usage Notes

1. If the QtrcWriteTextPrintF() function is called multiple times, there may be a noticeable performance




QtrcWriteTextPrintF() function. The variable should be periodically updated, to ensure a current view

of the component’s active trace level. Refer to the “QTRC Trace APIs” on page 72 for additional




3. The Format parameter and the corresponding Argument_List is used to write a string of characters as

trace data, in the same style as the printf() function. This provides a simple way to write out text trace

data with replacement values. For example, the Format could be something like ″Function myLocator()

returned %d″ and the argument list would be the return code variable myRC, if the function was

called with myRC=myLocator(). The Format string is assumed to be in the CCSID of the job.

4. The Format parameter should only contain characters in the invariant character set. This is also true






the QtrcWriteTextPrintF() function for each section.

Related Information



Trace Data






89—Write Text Trace Data Using Pointer-based Print Formatted


page 98—Write Text Trace Data Using Variable Argument List Print Formatted




Example

The following example uses ERROR-level, INFO-level, and VERBOSE-level trace points to write

formatted text trace data for a component named MYCOMP. The QtrcGetActiveLevel function is used,

since there are more than one trace points, as described in the Performance section of “QTRC Trace Tips”

on page 217. The VERBOSE-level component trace record will be written to the active trace collection if

the program is called with one parameter and the STRTRC CL command was used before calling the

example, specifying TRCTYPE((MYCOMP *VERBOSE)). The INFO-level component trace records will be

written to the active trace collection if the program is called with one parameter and the STRTRC CL

command was used before calling the example, specifying either TRCTYPE((MYCOMP *INFO)) or


TRCTYPE((MYCOMP *VERBOSE)). The ERROR-level component trace record will be written to the active

trace collection if the program is called with either no parameters or more than one parameter and the

STRTRC CL command was used before calling the example, specifying either TRCTYPE((MYCOMP

*ERROR)), TRCTYPE((MYCOMP *INFO)), or TRCTYPE((MYCOMP *VERBOSE)).



#include <qtrc.h>

#include <stdio.h>

#include <stdlib.h>

#include <errno.h>


{



int rc;

char *thePATH;

const char *defaultPATH = "/usr/bin:.:/QOpenSys/usr/bin";

/* Get active trace level now, for MYCOMP, to allow */

/* quick checks later on */


if (rc != 0) {

printf("QtrcGetActiveLevel() failed with error %d\n",

rc);

return -2;

}

if ((argc-1) == 1) {

/* Quick check of MYCOMP active trace level */


rc = QtrcWriteTextPrintF(QTRC_LEVEL_INFO,

myComp,

"SUBCOMP",

argv[0],

"Parameter 1 is %s", argv[1]);

if (rc != 0) {

printf("QtrcWriteTextPrintF() failed with error %d\n",

rc);

return -2;

}

}

}

else {

/* No need for quick check of MYCOMP active trace */

/* level since this error trace point should not */

/* normally be reached */

rc = QtrcWriteTextPrintF(QTRC_LEVEL_ERROR,

myComp,

"SUBCOMP",

argv[0],

"Number of parameters %d, return -1", (argc-1));

if (rc != 0) {


rc);

return -2;

}




return -1;

}

thePATH = getenv("PATH");


if (thePATH == NULL) {

/* PATH environment variable not set, use default PATH */



rc = QtrcWriteTextPrintF(QTRC_LEVEL_INFO,

myComp,

"SUBCOMP",

argv[0],

"PATH is not set, using %s", defaultPATH);

if (rc != 0) {


rc);

return -2;

}

}

thePATH = (char *)defaultPATH;

}


if (myCompActLvl >= QTRC_LEVEL_VERBOSE) {

rc = QtrcWriteTextPrintF(QTRC_LEVEL_VERBOSE,

myComp,

"SUBCOMP",

argv[0],

"PATH is %s", thePATH);

if (rc != 0) {


rc);

return -2;

}

}




return 0;

}

Example Output:



trace collection.



QtrcWriteTextVPrintF()—Write Text Trace Data Using Variable Argument

List Print Formatted


int QtrcWriteTextVPrintF





const char *Format,

va_list Argument_List);


#TOP_OF_PAGE

aplist.htm


The QtrcWriteTextVPrintF() function writes a component trace record as text string data, using a variable

argument list print formatted layout, to an active trace collection if certain trace conditions are met. Note:

Because of the variable argument list parameter, the QtrcWriteTextVPrintF() function is meant to be used

only in C and C++ programs.

The QtrcWriteTextVPrintF() uses the Format parameter to process the variable argument list specified by

the Argument_List parameter. The QtrcWriteTextVPrintF() function works just like the

“QtrcWriteTextPrintF()—Write Text Trace Data Using Print Formatted” on page 94 function, except that

Argument_List points to a list of arguments whose number can vary from call to call in the program.

These arguments should be initialized by va_start for each call. Format specifications, which begin with a

percent sign (%), are used to convert each corresponding argument list entry, and include the resulting

text string in the trace record. If there are more argument list entries than there are format specifications,

the extra arguments are evaluated and ignored. The results are undefined if there are not enough

argument list entries for all the format specifications.

Each call to the QtrcWriteTextVPrintF() function is considered a trace point. A component trace record is


conditions include:















Parameters

Coded_Level

(Input)


Component

(Input)



Subcomponent

(Input)





Function

(Input)




Format

(Input)


of the text to be written as a trace record. See the printf()—Print Formatted Characters for a

description of valid format strings and vprintf()—Print Argument Data for a description of how

the format specifications are used along with a variable argument list.

Argument_List

(Input)

Pointer to a list of arguments whose number can vary from call to call in the program. These

arguments should be initialized by va_start for each call. The variable argument list contains

entries to be formatted and written as part of the text string trace record.


None.

Return Value

0 QtrcWriteTextVPrintF() was successful. However, the component trace record will only be written


value QtrcWriteTextVPrintF() was not successful. An error condition was detected which would

prevent the component trace record from ever being written.

Error Conditions

If QtrcWriteTextVPrintF() was not successful, the error condition returned usually indicates one of the


listed here.




[EFAULT (page 223)]


Error Messages

None.

Usage Notes

1. If the QtrcWriteTextVPrintF() function is called multiple times, there may be a noticeable performance




QtrcWriteTextVPrintF() function. The variable should be periodically updated, to ensure a current






3. The Format parameter and the corresponding Argument_List parameter are used to write a string of

characters as trace data, in the same style as the vprintf() function. This provides a way to write a

function that takes a variable argument list, and use those arguments to write out text trace data with

replacement values. The Format string is assumed to be in the CCSID of the job.

4. The Format parameter should only contain characters in the invariant character set. This is also true






the QtrcWriteTextVPrintF() function for each section.

Related Information



Trace Data






Data Using Print Formatted


89—Write Text Trace Data Using Pointer-based Print Formatted


v vprintf()—Print Argument Data



Example

The following example provides two internal functions that can be used to write formatted text trace data

for a component named MYCOMP and a component named THATCOMP. This example shows how an

application can provide their own trace point functions that reduce the amount of code needed to write

similar trace records. The component trace records will be written to the active trace collection if the

STRTRC CL command was used before calling the example, specifying either TRCTYPE((MYCOMP

*INFO) (THATCOMP *VERBOSE)) or TRCTYPE((MYCOMP *VERBOSE) (THATCOMP *VERBOSE)).



#include <qtrc.h>

#include <stdarg.h>

void traceMYCOMP(unsigned int, char *, ...);

void traceV_THATCOMP(char *, ...);


{

int val = 63;

int val2 = 430;

int val3 = 82;


/* Trace val as INFO-level trace point for MYCOMP */

traceMYCOMP(QTRC_LEVEL_INFO,"val=%d",val);

/* Trace val2 and val3 for THATCOMP. The function */

/* always uses subcomponent SUBCOMP and a */

/* VERBOSE-level trace point. */

traceV_THATCOMP("val2=%d val3=%d", val2, val3);




return 0;

}

void traceMYCOMP(unsigned int tLvl, char *fmt, ...)

{

va_list argPtr;


int rc;

va_start(argPtr, fmt);

rc = QtrcWriteTextVPrintF(tLvl,

myComp,

NULL, /* No subcomponent defined */

NULL, /* No function defined */

fmt,

argPtr );

if (rc != 0) {

printf("QtrcWriteTextVPrintF() failed with error %d\n",

rc);

}

va_end(argPtr);

return;

}

void traceV_THATCOMP(char *fmt, ...)

{

va_list argPtr;

const char *thatComp = "THATCOMP";

const char *thatSubcomp = "SUBCOMP";

int rc;

va_start(argPtr, fmt);

rc = QtrcWriteTextVPrintF(QTRC_LEVEL_VERBOSE,

thatComp,

thatSubcomp,

NULL, /* No function defined */

fmt,

argPtr );

if (rc != 0) {

printf("QtrcWriteTextVPrintF() failed with error %d\n",

rc);

}

va_end(argPtr);

return;

}

Example Output:



trace collection.




Service APIs

The Service APIs include:

v “Change Contact Information (QEDCHGIN) API” (QEDCHGIN) updates the contact information that

is supplied to a service provider when a problem is reported or a PTF is requested.

v “Collect Hung Job Service Documentation (QPDETHNG) API” on page 109 (QPDETHNG) dumps

documentation associated with the hung job to help service determine the cause of the hang.

v “Convert Format of Service Information (QPDETCVT) API” on page 110 (QPDETCVT) allows you

convert messages and liclog information to an XML document

v “Filter Problem (QSXFTRPB) API” on page 128 (QSXFTRPB) applies the currently active problem log

filter to a problem log entry.

v “Retrieve Contact Information (QEDRTVCI) API” on page 129 (QEDRTVCI) returns the contact

information that is supplied to a service provider when a problem is reported or a PTF is requested.

v “Retrieve Policy Data (QPDETRTV) API” on page 134 (QPDETRTV) retrieves policy data.

v “Retrieve Service Attributes (QESRSRVA) API” on page 138 (QESRSRVA) retrieves service information

such as the service provider and whether automatic problem analysis should be performed.

v “Retrieve XML Service Information (QSCRXMLI) API” on page 145 (QSCRXMLI) Lists service

information like messages from a nonprogram message queue or messages sent to the program

message queue of a job, in XML format, and optionally stores the output in a stream file.

v “Send Service Request (QPDETSND) API” on page 155 (QPDETSND) sends the request to the Service

Monitor or to the Service Control job.

v “Set User Policy (QPDETPOL) API” on page 159 (QPDETPOL) allows the changing of user policies

related to service.


Change Contact Information (QEDCHGIN) API


1 Contact information Input Char(*)

2 Length of contact information Input Binary(4)

3 Format name Input Char(8)



The Change Contact Information (QEDCHGIN) API updates the contact information that is supplied to a

service provider when a problem is reported or a PTF is requested.


None.


Contact information

INPUT; CHAR(*)


#TOP_OF_PAGE

aplist.htm

#TOP_OF_PAGE

aplist.htm

The contact information that is changed.

Length of contact information

INPUT; BINARY(4)

The total length in bytes of the contact information input variable.

Format name

INPUT; CHAR(8)

The format of the contact information input data. The possible values are:

CNTC0100

This format updates all of the contact information. See “CNTC0100 Format” for details.

Error code

I/O; CHAR(*)


parameter.

CNTC0100 Format

Use this format when changing contact information. For detailed descriptions of the fields in this table,

see “Field Descriptions” on page 106.

Offset

Type Field Dec Hex

0 0 Char(36) Company name

36 24 Char(36) Contact name

72 48 Char(20) Primary telephone number

92 5C Char(20) Help desk or pager number

112 70 Char(20) Primary fax number

132 84 Char(20) Alternative fax number

152 98 Char(36) Street address line 1

188 BC Char(36) Street address line 2

224 E0 Char(36) Street address line 3

260 104 Char(36) City or locality

296 128 Char(36) State or province

332 14C Char(20) Country or region

352 160 Char(12) Postal code

364 16C Binary(4) Offset to primary electronic mail address

368 170 Binary(4) Length of primary electronic mail address

372 174 Binary(4) Offset to alternative electronic mail address

376 178 Binary(4) Length of alternative electronic mail address

380 17C Binary(4) Media for mailing PTFs

384 180 Char(10) National language version

394 18A Char(2) Reserved


Offset

Type Field Dec Hex

396 18C Binary(4) Call central site support

400 190 Char(8) Customer identifier 1


416 1A0 Char(8) Customer identifier 3


432 1B0 Char(8) Customer identifier 5

440 1B8 Char(7) Contract identifier 1

447 1BF Char(7) Contract identifier 2

454 1C6 Char(7) Contract identifier 3

461 1CD Char(7) Contract identifier 4

468 1D4 Char(7) Contract identifier 5

475 1DB Char(1) Reserved2

476 1DC Binary(4) Offset to customer description 1

480 1E0 Binary(4) Length of customer description 1

484 1E4 Binary(4) Offset to customer description 2


492 1EC Binary(4) Offset to customer description 3

496 1F0 Binary(4) Length of customer description 3

500 1F4 Binary(4) Offset to customer description 4


508 1FC Binary(4) Offset to customer description 5

512 200 Binary(4) Length of customer description 5

516 204 Binary(4) Offset to contract description 1

520 208 Binary(4) Length of contract description 1

524 20C Binary(4) Offset to contract description 2








* * Char(*) Primary electronic mail address

* * Char(*) Alternative electronic mail address

* * Char(*) Customer description 1





* * Char(*) Contract description 1


Offset

Type Field Dec Hex





Field Descriptions

Alternative electronic mail address. The electronic mail (e-mail) address where information for the

person specified for the Contact can be sent, if the primary e-mail address is not available.

*SAME The value does not change.

*NONE There is no alternative electronic mail address for the contact person.

character-value Specify the alternative electronic mail address.

Alternative fax number. The complete telephone number where information for the Contact can be faxed,

if the primary fax number is not available. This number should include the area code, exchange numbers,

and the extension.


*NONE There is no alternative fax number for the contact person.

character-value Specify the alternative fax number.

Call central site support. It will be used to indicate that a customer wants their Central Site Support

desk called by the CE or the Product Support center. The call central site support options available are:

0 = *NO The central site support desk is not called.

1 = *YES The central site support desk will be called by the CE or the Product Support center.

-1 = *SAME The value does not change.

City or locality. The city or locality name for the location to which you want your service provider to

send parts or assistance.


character-value Specify the city or locality.

Company name. The name of the organization that owns or is responsible for this system. The name

should appear in this field as it appears on a mailing label.


character-value Specify the company name.

Contact name. The name of the person in your organization who is responsible for repairs and

maintenance on the system. This person may be called by the service provider with information or

assistance for a system problem. Also, parts or PTFs may be sent to this person.


character-value Specify the contact person’s name.


Contract identifier 1, 2, 3, 4 and 5. A unique identifier IBM assigned to the customer’s services contract.

This number enables the look-up of all customer purchased services under the identified contract.


*NONE No additional contract identifier information is provided.

character-value Specify the contract identifier. Up to five lines of contract identifier information can be specified.

Each line is a separate parameter element. The value cannot contains blanks and must contain

only digits 0-9 and uppercase letters A-Z

Contract description 1, 2, 3, 4 and 5. The contract description.



character-value Specify the contract description. Up to five lines of contract identifier information can be specified.

Each line is a separate parameter element. Which can be up to 256 characters long.

Country or region. The country or region where the company is located to which the service provider

should send parts or assistance.


character-value Specify the country or region.

Customer identifier 1, 2, 3, 4 and 5. A unique number that IBM has assigned to the customer. This

number is used to identify the customer during a multitude of business and services transactions.


*NONE No additional customer identifier information is provided.

character-value Specify the customer identifier. Up to five lines of customer identifier information can be specified.

Each line is a separate parameter element. The value cannot contains blanks and must contain

only digits 0-9.

Customer description 1, 2, 3, 4 and 5. The customer description.



character-value Specify the customer description. Up to five lines of customer identifier information can be

specified. Each line is a separate parameter element which can be up to 256 characters long.

Help desk or pager number. The complete Help desk or pager number. This number should include the

area code, exchange numbers, and the extension.


*NONE There is no Help desk telephone number.

character-value Specify the Help desk telephone number.

Length of alternative electronic mail address. The length of the alternative electronic mail address.

Length of contract description 1, 2, 3, 4 and 5. The length of contract description 1, 2, 3, 4 and 5.


Length of customer description 1, 2, 3, 4 and 5. The length of customer description 1, 2, 3, 4 and 5.

Length of primary electronic mail address. The length of the primary electronic mail address.

Media for PTFs. The media currently used for mailing program temporary fixes (PTFs). The media

options available are:

0 = *SAME The value does not change.

1 =

*AUTOMATIC

The system will automatically select the media to be used for sending PTFs.

If the system does

not detect any device, the default value will be *DVDROM.

2 = *CDROM PTFs will be sent on CD-ROM media.

3 =

*DVDROM

PTFs will be sent on DVD-ROM media.

National language version. The national language version code currently being used for PTF cover

letters. If the cover letter you ordered has not been translated into this language the cover letter will be

sent in U.S. English.


*PRIMARY The language version for the currently installed primary national language on the system is used.

character-value Specify the preferred language version code to be used for PTF cover letters.

Offset to alternative electronic mail address. The offset to the alternative electronic mail address.

Offset to contract description 1,2,3,4 and 5. The offset to contract description 1, 2, 3, 4 and 5.

Offset to customer description 1,2,3,4 and 5. The offset to customer description 1, 2, 3, 4 and 5.

Offset to primary electronic mail address. The offset to the primary electronic mail address.

Postal code. The Postal code for the location to which the service provider should send parts or

assistance.


character-value Specify the Postal code.

Primary electronic mail address. The electronic mail (e-mail) address where information for the person

specified for the Contact can be sent.


*NONE There is no primary electronic mail address for the contact person.

character-value Specify the primary electronic mail address.

Primary fax number. The complete telephone number where information for the Contact can be faxed.

This number should include the area code, exchange numbers, and the extension


*NONE There is no primary fax number for the contact person.

character-value Specify the primary fax number.

Primary telephone number. The complete telephone number where the person named for the Contact

may be reached most often. This number should include the area code, exchange numbers, and the

extension.



character-value Specify the primary telephone number.

State or province. The state or province names for the location to which you want your service provider

to send parts or assistance.


*NONE There is no State or province.

character-value Specify the State or province.

Street address lines 1, 2 and 3. The postal number and street name of the location to which you want

your service provider to send parts or assistance for the problem. This should not be a post office box.


*NONE No additional street address information is provided. This value is valid for lines 2 and 3, but not

for line 1.

character-value Specify the street address. Up to three lines of street address information can be specified. Each

line is a separate parameter element, which can be up to 36 characters long.

Error Messages





CPF3CF2 Error(s) occurred during running of &1 API.

CPF3C19 Error occurred with receiver variable specified.

CPF3C21 Format name &1 is not valid.

CPF3C24 Length of the receiver variable is not valid.

CPF8C83 One or more required fields to add contact information missing. See previous messages.



Collect Hung Job Service Documentation (QPDETHNG) API


1 Job name Input Char(10)

2 Job user Input Char(10)

3 Job number Input Char(6)



The Collect Hung Job Service Documentation (QPDETHNG) API dumps documentation associated with

the hung job to help service determine the cause of the hang.


#TOP_OF_PAGE

aplist.htm



Special authorities needed: *JOBCTL and either *SERVICE or be authorized to the Service Dump

function of the i5/OS®



ID of QIBM_SERVICE_DUMP, can also be used to change the list of users that are allowed to

perform dump operations.


Job name

INPUT; CHAR(10)

The name of the hung job.

Job user

INPUT; CHAR(10)

The user of the hung job.

Job number

INPUT; CHAR(6)

The number of the hung job.

Error code

I/O; CHAR(*)


parameter.

Error Messages




CPF3CF2 Error(s) occurred during running of * API.

CPFC1D Input variable length in parameter * not valid.

CPF3C1E Required parameter * omitted.

CPF3C17 Error occurred with input data parameter.

CPF3C21 Format name * is not valid.

CPF3C4A Value not valid for field *.

CPF3C4B Value not valid for field *.

CPF3C4C Value not valid for field *.

CPF9872 Program or service program * in library * ended. Reason code *.



Convert Format of Service Information (QPDETCVT) API




#TOP_OF_PAGE

aplist.htm


3 Format of receiver variable Input Char(8)

4 Information to convert Input Char(*)

5 Format of information to convert Input Char(8)


Default Public Authority: *USE Threadsafe: Yes

The Convert Format of Service Information(QPDETCVT) API takes the data input and converts it to a

string containing an XML object.



No authorities needed.


Receiver Variable

OUTPUT; CHAR(*)

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

formatted XML string.


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 receiver variable” on page 112 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 -

Format for LIC

Log conversion

(STRWCH

command or

QSCSWCH API)”

on page 113

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 -

Format for

message

conversion

(STRWCH

command or

QSCSWCH API)”

on page 114

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 -

Format for

message

conversion

(QGYOLMSG

API or

QMHLSTM

API)” on page 115


the Open List of Messages (QGYOLMSG) API or the List Nonprogram Messages (QMHLSTM)

API. For more information, see “CVTS0300 - Format for message conversion (QGYOLMSG API or

QMHLSTM API)” on page 115 for information to convert. The format of the receiver variable will


“CVTS0400 -

Format for

message

conversion

(QGYOLJBL API

or QMHLJOBL

API)” on page 116


the Open List of Job Log Messages (QGYOLJBL) API or the List Job Log Messages (QMHLJOBL)

API. For more information, see “CVTS0400 - Format for message conversion (QGYOLJBL API or

QMHLJOBL API)” on page 116 for information to convert. The format of the receiver variable will


CVTS0500

(page “CVTS0500

- Format for

message

conversion

(QMHOLHST)”

on page 117)


the Open List of History Log Messages (QMHOLHST) API. For more information, see CVTS0500

Format (page “CVTS0500 - Format for message conversion (QMHOLHST)” on page 117) for

information to convert. The format of the receiver variable will be described by the XSD file

specified in the returned XML object.

“CVTS0600 -

Format for PAL

conversion

(STRWCH

command or

QSCSWCH API)”

on page 118

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(*)


parameter.

CVTR0100 - Format for receiver variable

The following table shows the format of the returned information. For a detailed description of each field,

see “Field Descriptions” on page 119.


QGYOLMSG.htm

QMHLSTM.htm

QMHLSTM.htm

QGYOLJBL.htm

QMHLJOBL.htm

QMHLJOBL.htm

qmholhst.htm

Offset

Type Field Dec Hex

0 0 BINARY(4) Bytes returned

4 4 BINARY(4) Bytes available

8 8 BINARY(4) XML data length

12 C CHAR(*) XML data

CVTS0100 - Format for LIC Log conversion (STRWCH command or

QSCSWCH API)

The following table shows the input for converting a LIC Log to XML. Any data not available should be

initialized with ’00’x. For a detailed description of each field, see “Field Descriptions” on page 119.

Offset

Type Field Dec Hex

0 0 BINARY(4) Length of watch information

4 4 CHAR(4) LIC Log major code

8 8 CHAR(4) LIC Log minor code

12 C CHAR(8) LIC Log identifier

20 14 CHAR(8) LIC Log timestamp

28 1C CHAR(8) TDE number

36 24 CHAR(16) Task name

52 34 CHAR(30) Server type

82 52 CHAR(2) Exception ID

84 54 CHAR(10) LIC job name

94 5E CHAR(10) LIC job user name

104 68 CHAR(6) LIC job number

110 6E CHAR(4) Reserved

114 72 CHAR(8) Thread ID

122 7A CHAR(8) LIC module compile binary timestamp

130 82 CHAR(8) LIC module offset

138 8A CHAR(8) LIC module RU name

146 92 CHAR(48) LIC module name

194 DA CHAR(128) LIC module entry point name

322 142 CHAR(1) LIC Log compare against specified


324 144 BINARY(4) Offset to comparison data

328 148 BINARY(4) Length of comparison data

332 14C CHAR(10) LIC log compare against

* * CHAR(*) LIC Log comparison data


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” on page 119.

Offset

Type Field Dec Hex


4 4 CHAR(7) Message ID


12 C CHAR(10) Message queue name

22 16 CHAR(10) Message queue library

32 20 CHAR(10) Job name

42 2A CHAR(10) Job user name



62 3E CHAR(256) Sending program name

318 13E CHAR(10) Sending module name

328 148 BINARY(4) Offset to sending procedure name

332 14C BINARY(4) Length of sending procedure name

336 150 CHAR(10) Receiving program name

346 15A CHAR(10) Receiving module name

356 164 BINARY(4) Offset to receiving procedure name

360 168 BINARY(4) Length of receiving procedure name

364 16C BINARY(4) Message severity

368 170 CHAR(10) Symbolic message type

378 17A CHAR(8) Message timestamp

386 182 CHAR(4) Message key

390 186 CHAR(10) Message file name

400 190 CHAR(10) Message file library


412 19C BINARY(4) Offset to comparison data

416 1A0 BINARY(4) Length of comparison data

420 1A4 CHAR(10) Compare against

430 1AE CHAR(10) Reserved

432 1B0 BINARY(4) Comparison data CCSID

436 1B4 BINARY(4) Offset where comparison data was found

440 1B8 BINARY(4) Offset to message replacement data

444 1BC BINARY(4) Length of message replacement data

448 1C0 BINARY(4) Replacement data CCSID

452 1C4 CHAR(10) Sending user profile

462 1CE CHAR(10) Target job name


Offset

Type Field Dec Hex

472 1D8 CHAR(10) Target job user name

482 1E2 CHAR(6) Target job number

* * CHAR(*) Sending procedure name

* * CHAR(*) Receiving procedure name

* * CHAR(*) Message comparison data

* * CHAR(*) Message replacement data

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” on page 119. Any data not available should be initialized with ’00’x.

Offset

Type Field Dec Hex

0 0 BINARY(4) Length of fixed header

4 4 BINARY(4) Offset to first message

8 8 BINARY(4) Number of messages to convert

These fields repeat for

each message identifier

specified.

BINARY(4) Displacement to the next entry

BINARY(4) Displacement to fields

BINARY(4) Number of fields

BINARY(4) Message severity

CHAR(7) Message identifier

CHAR(2) Message type

CHAR(4) Message key

CHAR(10) Message file name

CHAR(10) Message file library specified at send time

CHAR(10) Message queue

CHAR(10) Message queue library used

CHAR(7) Date sent

CHAR(6) Time sent

CHAR(6) Microseconds

CHAR(*) Reserved


These fields repeat for each identifier field specified. BINARY(4) Displacement to the

next field information

BINARY(4) Length of field

information

BINARY(4) Identifier field

CHAR(1) Type of data

CHAR(1) Status of data

CHAR(14) Reserved

BINARY(4) Length of data

CHAR(*) Data

CHAR(*) Reserved

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”

on page 119. Any data not available should be initialized with ’00’x.

Offset

Type Field Dec Hex




12 C CHAR(10) Job name

22 16 CHAR(10) Job user name




specified.

BINARY(4) Displacement to the next entry

BINARY(4) Displacement to fields

BINARY(4) Number of fields




CHAR(4) Message key


CHAR(10) Message file library specified at send time

CHAR(7) Date sent

CHAR(6) Time sent



CHAR(*) Reserved


These fields repeat for each identifier field

specified.

BINARY(4) Displacement to the next

field information returned

BINARY(4) Length of field

information returned

BINARY(4) Identifier field

CHAR(1) Type of data


CHAR(14) Reserved

BINARY(4) Length of data

CHAR(*) Data

CHAR(*) Reserved

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” on page 119.

Offset

Type Field Dec Hex





Offset

Type Field Dec Hex



specified.

BINARY(4) Length of this entry





CHAR(10) Message file library

CHAR(7) Date sent

CHAR(6) Time sent


CHAR(10) Job Name

CHAR(10) Job User Name

CHAR(6) Job Number

CHAR(10) From user


CHAR(3) Reserved

BINARY(4) Displacement to the first level message or immediate text

BINARY(4) Length of the first level message or immediate text

BINARY(4) Displacement to the message replacement data

BINARY(4) Length of message replacement data

BINARY(4) CCSID for text

BINARY(4) CCSID conversion status indicator for text

BINARY(4) CCSID for data

BINARY(4) CCSID conversion status indicator for data

CHAR(*) Reserved

CHAR(*) First level message or immediate text

CHAR(*) Message replacement data

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” on page 119.

Offset

Type Field Dec Hex



12 C CHAR(10) Device name

22 16 CHAR(4) Device type

26 1A CHAR(4) Model

30 1E CHAR(15) Serial number


Offset

Type Field Dec Hex

45 2D CHAR(10) Resource name

55 37 CHAR(8) Log identifier

63 3F CHAR(8) PAL timestamp

71 47 CHAR(4) Reference code

75 4B CHAR(8) Secondary code

83 53 CHAR(8) Table identifier

91 5B CHAR(1) Reserved

92 5C BINARY(4) Sequence





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:

0 No conversion was needed because the CCSID of the data matched the CCSID you wanted the

data converted to.

1 No conversion occurred because either the data was 65535 or the CCSID you wanted the data

converted to was 65535.

2 No conversion occurred because you did ask for any data to be returned, or there was no

*CCHAR type data.

3 The data was converted to the CCSID specified using the best fit conversion tables.

4 A conversion error occurred using the best fit conversion tables so a default conversion was

attempted. This completed without error.

-1 An error occurred on both the best fit and default conversions. The data was not converted.

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

0 No conversion was needed because the CCSID of the text matched the CCSID you wanted the

text converted to.

1 No conversion occurred because either the text was 65535 or the CCSID you wanted the text

converted to was 65535.

2 No conversion occurred because you did not ask for any text to be returned.

3 The text was converted to the CCSID specified using the best fit conversion tables.

4 A conversion error occurred using the best fit conversion tables so a default conversion was

attempted. This completed without error.

-1 An error occurred on both the best fit and default conversions. The data was not converted.


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.


*MSGDTA The message comparison data was compared against the message replacement data.

*FROMPGM The message comparison data was compared against the sending program name.

*TOPGM The message comparison data was compared against the receiving program name.

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:

12 - when using format CVTS0300

or CVTS0500

38 - when using format CVTS0400

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:

*ALL The LIC log comparison data was compared against all the fields described below.

*TDENBR The LIC log comparison data was compared against the TDE number.

*TASKNAME The LIC log comparison data was compared against the task name.

*SVRTYPE The LIC log comparison data was compared against the server type.

*JOBNAME The LIC log comparison data was compared against the LIC job name.

*JOBUSR The LIC log comparison data was compared against the LIC job user name.

*JOBNBR The LIC log comparison data was compared against the LIC job number.

*THDID The LIC log comparison data was compared against the thread ID.

*EXCPID The LIC log comparison data was compared against the exception ID.

*MODNAME The LIC log comparison data was compared against the LIC module name.

*MODRUNAME The LIC log comparison data was compared against the LIC module replacement unit name.

*MODEPNAME The LIC log comparison data was compared against the LIC module entry point name.

*MODOFFSET The LIC log comparison data was compared against the LIC module offset.

*MODTSP The LIC log comparison data was compared against the LIC module compile timestamp.

LIC log compare against specified. The character indicating if the LIC log compare against field was

specified. The possible values are:

0 The LIC log compare against field was not specified.

1 The LIC log compare against field was specified.

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:

Value Message Type

*JOBLOG The message was found in the job specified in the target job name, target job user name and target job

number fields.

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:

Value Message Type

01 Completion

02 Diagnostic

04 Informational

05 Inquiry

06 Sender’s copy

08 Request

10 Request with prompting

14 Notify, exception already handled when API is called

15 Escape, exception already handled when API is called

16 Notify, exception not handled when API is called

17 Escape, exception not handled when API is called

21 Reply, not checked for validity

22 Reply, checked for validity

23 Reply, message default used

24 Reply, system default used

25 Reply, from system reply list

26 Reply, from exit program

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.


qwccvtdt.htm

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:

blank The data returned is complete.

A The caller of the API was not authorized to view the data. This occurs when the caller of the API is not

authorized to the message file or message file library containing a stored message being listed.

D The data was damaged. This occurs when the message file or library specified at send time for a stored

message is damaged when the API is called.

U The data was unavailable. This occurs when the message file or library specified at send time for a

stored message is exclusively used by another process when the API is called.

N The data was not found. This occurs when the message file or library specified at send time for a

stored message cannot be found or resolved when the API is called.

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:

0101 When the status of data field is not blank, the alert option field identifier contains blanks.

0301, 0302 When the status of data field is not blank, these message field identifiers contain message text

about the problem encountered while attempting to access the message file. Both fields have the

replacement data substituted.

0401, 0402, 0403,

0404

When the status of data field is not blank, these message help field identifiers contain the text of

the message regarding the problem encountered while attempting to access the message file. All

fields have the replacement data substituted. The message help with formatting characters and

message help with replacement data and formatting characters field identifiers also have the

message formatting characters included.

0501 When the status of data field is not blank, the default reply field identifier contains the system

default reply.

0801 When the status of data field is not blank, the message file library used field identifier contains

blanks.

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:

v The status of data field is set to N.

v 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:

*COMP Completion

*DIAG Diagnostic

*ESCAPE Escape


*INFO Informational

*INQ Inquiry

*NOTIFY Notify

*RQS Request

*STATUS Status

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.

C The data is returned in character format.

B The data is returned in binary format.

M The data is returned in a mixed form

XML data. The XML data being returned.

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

Error Messages



CPF0CC1 Error initializing the XML parser.





CPF3C36 Number of parameters, &1, entered for this API was not valid.




Top | Problem Management APIs | APIs by category

Filter Problem (QSXFTRPB) API


1 Problem log identifier Input Char(30)



The Filter Problem (QSXFTRPB) API applies the currently active problem log filter to a problem log entry.

The system value for the problem filter (QPRBFTR) identifies the active filter currently being used.

Multiple filters can be defined, but only one can be active at a time. The QSXFTRPB API can be used at

any time.


Problem log identifier

INPUT; CHAR(30)

The problem to be retrieved, updated, and sent through the active filter. The problem log

identifier has two parts: a problem ID number and the origin system. See “Format for the

Problem Log Identifier.”

Error code

I/O; CHAR(*)


parameter.



*USE

Format for the Problem Log Identifier

Offset

Type Field Dec Hex

0 0 CHAR(10) Problem ID number

10 A CHAR(20) Origin system


#TOP_OF_PAGE

aplist.htm

Field Descriptions

Origin system. The node name of the origin system (the format is network ID.control point name).

Problem ID number. The number the system generates to identify a problem.

Error Messages





CPF7A82 E Error occurred while applying the problem filter.

CPF7A83 E Problem filter &1/&2 not found.

CPF7A93 E Problem &2 currently in use by job &1.

CPF8160 E &8 damage on &4 type &3.

CPF9803 E Cannot allocate object &2 in library &3.




Retrieve Contact Information (QEDRTVCI) API







The Retrieve Contact Information (QEDRTVCI) API returns the contact information that is supplied to a

service provider when a problem is reported or a PTF is requested.


None.


Receiver variable

OUTPUT; CHAR(*)

The receiver variable that receives the information requested. You can specify the size of the area

to be smaller than the format requested as long as you specify the length parameter correctly. As

a result, the API returns only the data that the area can hold.


INPUT; BINARY(4)

The length of the receiver variable provided. The length of receiver variable parameter may be

specified up to the size of the receiver variable specified in the user program. If the length of

receiver variable parameter specified is larger than the allocated size of the receiver variable

specified in the user program, the results are not predictable. The minimum length is 8 bytes.


#TOP_OF_PAGE

aplist.htm

Format name

INPUT; CHAR(8)

The format of the contact information to be returned. The possible values are:

CNTI0100

This format returns all of the contact information. See “CNTI0100 Format” for details.

Error code

I/O; CHAR(*)


parameter.

CNTI0100 Format

The following information is returned by this API when CNTI0100 format. For detailed descriptions of

the fields in the table, see “Field Descriptions” on page 132.

Offset

Type Field Dec Hex

0 0 Binary(4) Bytes returned

4 4 Binary(4) Bytes available

8 8 Char(36) Company name

44 2C Char(36) Contact name

80 50 Char(20) Primary telephone number

100 64 Char(20) Help desk or pager number

120 78 Char(20) Primary fax number

140 8C Char(20) Alternative fax number

160 A0 Char(36) Street address line 1

196 C4 Char(36) Street address line 2

232 E8 Char(36) Street address line 3

268 10C Char(36) City or locality

304 130 Char(36) State or province

340 154 Char(20) Country or region

360 168 Char(12) Postal code

372 174 Binary(4) Offset to primary electronic mail address

376 178 Binary(4) Length of primary electronic mail address

380 17C Binary(4) Offset to alternative electronic mail address

384 180 Binary(4) Length of alternative electronic mail address

388 184 Binary(4) Media for mailing PTFs

392 188 Char(4) National language version

396 18C Binary(4) Call central site support




Offset

Type Field Dec Hex



432 1B0 Char(8) Customer identifier 5



454 1C6 Char(7) Contract identifier 3

461 1CD Char(7) Contract identifier 4

468 1D4 Char(7) Contract identifier 5

475 1DB Char(1) Reserved

476 1DC Binary(4) Offset to customer description 1


484 1E4 Binary(4) Offset to customer description 2


492 1EC Binary(4) Offset to customer description 3


500 1F4 Binary(4) Offset to customer description 4


508 1FC Binary(4) Offset to customer description 5

512 200 Binary(4) Length of customer description 5











* * Char(*) Primary electronic mail address

* * Char(*) Alternative electronic mail address











Offset

Type Field Dec Hex


Field Descriptions

Alternative electronic mail address. The electronic mail (e-mail) address where information for the

person specified for the Contact can be sent, if the primary e-mail address is not available. The e-mail is

returned as UTF8. The following special values might be returned:

*NONE There is no alternative electronic mail address for the contact person.

Alternative fax number. The complete telephone number where information for the Contact can be faxed,

if the primary fax number is not available. This number should include the area code, exchange numbers,

and the extension. The following special values might be returned:

*NONE There is no alternative fax number for the contact person.




Call central site support. It will be used to indicate that a customer wants their Central Site Support


1 = *YES The central site support desk will be called by the CE or the Product Support center.

0 = *NO As a default, the central site support desk is not called.

City or locality. The City or locality name for the location to which you want your service provider to

send parts or assistance.

Company name. The name of the organization that owns or is responsible for this system. The name

should appear in this field as it appears on a mailing label.

Contact name. The name of the person in your organization who is responsible for repairs and

maintenance on the system. This person may be called by the service provider with information or

assistance for a system problem. Also, parts or PTFs may be sent to this person.

Contract identifier 1, 2, 3, 4 and 5. The contract identifier. The following special values might be

returned:


Contract description 1, 2, 3, 4 and 5. The contract description is returned as UTF8. The following special

values might be returned:

*NONE No additional contract description information is provided.


Country or region. The Country or region where the company is located to which the service provider

should send parts or assistassnce.

Customer identifier 1, 2, 3, 4 and 5. The customer identifier. The following special values might be

returned:


Customer description 1, 2, 3, 4 and 5. The customer description is returned as UTF8. The following

special values might be returned:

*NONE No additional customer description information is provided.

Help desk or pager number. The complete Help desk or pager number. This number should include the

area code, exchange numbers, and the extension. The following special values might be returned:

*NONE There is no Help desk or pager number.

Length of alternative electronic mail address. The length of the alternative electronic mail address.

Length of contract description 1, 2, 3, 4 and 5. The length of contract description 1, 2, 3, 4 and 5.

Length of customer description 1, 2, 3, 4 and 5. The length of customer description 1, 2, 3, 4 and 5.

Length of primary electronic mail address. The length of the primary electronic mail address.

Media for PTFs. The media currently used for mailing program temporary fixes (PTFs). The media

options available are:

1 =

*AUTOMATIC

The system will automatically select the media to be used for sending PTFs.

2 = *CDROM PTFs will be sent on CD-ROM media.

3 =

*DVDROM

PTFs will be sent on DVD-ROM media.

National language version. The national language version code currently being used for PTF cover

letters. If the cover letter you ordered has not been translated into this language the cover letter will be

sent in U.S. English.

Offset to alternative electronic mail address. The offset to the alternative electronic mail address.

Offset to contract description 1,2,3,4 and 5. The offset to contract description 1, 2, 3, 4 and 5.

Offset to customer description 1,2,3,4 and 5. The offset to customer description 1, 2, 3, 4 and 5.

Offset to primary electronic mail address. The offset to the primary electronic mail address.

Postal code. The Postal code for the location to which the service provider should send parts or

assistance.

Primary electronic mail address. The electronic mail (e-mail) address where information for the person

specified for the Contact can be sent. The e-mail is returned as UTF8. The following special values might

be returned:


*NONE There is no primary electronic mail address for the contact person.

Primary fax number. The complete telephone number where information for the Contact can be faxed.

This number should include the area code, exchange numbers, and the extension. The following special


*NONE There is no primary fax number for the contact person.

Primary telephone number. The complete telephone number where the person named for the Contact

may be reached most often. This number should include the area code, exchange numbers, and the

extension.

State or province. The state or province names for the location to which you want your service provider

to send parts or assistance. The following special values might be returned:

*NONE There is no State or province.

Street address lines 1, 2 and 3. The postal number and street name of the location to which you want

your service provider to send parts or assistance for the problem. This should not be a post office box.

The following special values might be returned:

*NONE No additional street address information is provided. This value is valid for lines 2 and 3, but not

for line 1.

Error Messages









CPF8C81 No Contact Information is available.



Retrieve Policy Data (QPDETRTV) API






#TOP_OF_PAGE

aplist.htm



The Retrieve Policy Data (QPDETRTV) API retrieves policy data.


Special Authority to use the API

*SERVICE


Receiver variable

OUTPUT; CHAR(*)

The variable that will receive the policy information being retrieved. For the format, see “Format

of Data Returned.”


INPUT; BINARY(4)

The length of the receiver variable described in Format of data returned. If the length is larger

than the size of the receiver variable, the results may not be predictable. The minimum length is 8

bytes.

Format name

INPUT; CHAR(8)

The format of the information to be returned. You must use one of the following format names:

“RPOL0100 - Retrieve service cleanup interval” on page 136

Retrieve service cleanup interval.

“RPOL0200 - Retrieve problem documentation level” on page 136

Retrieve problem documentation level.

“RPOL0300 - Retrieve maximum PTF order size and downloading time” on page 136

Retrieve maximum PTF order size and downloading time.

RPOL0400 (page “RPOL0400 - Retrieve period of time for problem processing” on page 136)

Retrieve period of time for duplicate problem processing.

“RPOL0500 - Retrieve preferred action when reporting a problem” on page 136

Retrieve an preferred action when reporting a problem.

Error code

I/O; CHAR(*)


parameter.

Format of Data Returned

The receiver variable holds the policy information returned.


RPOL0100 - Retrieve service cleanup interval

Offset

Type Field Dec Hex



8 8 Binary(4) Number of days

RPOL0200 - Retrieve problem documentation level

Offset

Type Field Dec Hex



8 8 Char(10) Problem documentation level

RPOL0300 - Retrieve maximum PTF order size and downloading time

Offset

Type Field Dec Hex



8 8 Binary(4) Maximum PTF order size over LAN

12 C Binary(4) Maximum PTF order size over a modem

16 10 Binary(4) Maximum time for downloading a PTF order via LAN

20 14 Binary(4) Maximum time for downloading a PTF order via modem

RPOL0400 - Retrieve period of time for problem processing

Offset

Type Field Dec Hex



8 8 Binary(4) Time for duplicate problem processing

RPOL0500 - Retrieve preferred action when reporting a problem

Offset

Type Field Dec Hex



8 8 Binary(4) Number of preferred actions


Offset

Type Field Dec Hex

12 C Array of BIN(4) Preferred actions

Field Descriptions




Maximum PTF order size over a modem. The maximum size in megabytes for a PTF order to be

delivered over a modem. A value of -1 indicates PTF orders of any size are delivered over a modem. A

value of 100 MB (MB equals approximately 1 000 000 bytes) is used if a lower value is retrieved.

Maximum PTF order size over LAN. The maximum size in megabytes for a PTF order to be delivered

over the local area network (LAN). A value of -1 indicates PTF orders of any size are delivered over the

LAN. A value of -1 is used if a value lower than 100 MB (MB equals approximately 1 000 000 bytes) is

retrieved.

Maximum time for downloading a PTF order via LAN. The maximum time in minutes for

downloading a PTF order via LAN. A value of -1 indicates PTF order can take any time for downloading

the order. This policy is shipped with a default value of -1.

Maximum time for downloading a PTF order via Modem. The maximum time in minutes for

downloading a PTF order via modem. A value of -1 indicates PTF order can take any time for

downloading the order. This policy is shipped with a default value of 60.

Number of days. The number of days an object covered by this policy is allowed to exist before being

deleted by the Service Monitor. Objects covered by this policy are: Service Monitor logs and Integrated

File System files created by the FFDC process.

This policy is shipped with a default value of 7.

Number of preferred actions. The number of preferred actions when reporting a problem.

Preferred actions. Indicates what the preferred actions when reporting a problem are. The following

values are returned:

0 No preferred action is selected (PTFs are downloaded). This is the defalult value.

1 Do not download PTFs.

Problem documentation level. Indicates how much problem documentation should be included when

problems are automatically reported to the service provider Only the following values are returned:

*BASE Minimal documentation is sent in the service request record. No additional data will be uploaded.

*DEFAULT Minimal documentation will be sent in the service request record. If no fix for the problem is found,

additional documentation will be automatically uploaded. Additional documentation may include

information such as joblogs and service dumps.

Time for duplicate problem processing. The number of days to check for duplicate problem to avoid

creating duplicate problem log entries. If a duplicate problem occurs within the specified number of days,


the existing problem log entry will be updated rather than creating a new problem log entry. If 0 is

specified, duplicate problem checking will not be performed. This policy is shipped with a default value

of 30. This policy cannot be set to a value more than 30 days.

Error Messages





CPF3C1D Input variable length in parameter * not valid.







CPF9872 Program or service program * in library * ended. Reason code *.



Retrieve Service Attributes (QESRSRVA) API




3 Number of service attribute keys Input Binary(4)

4 Service attribute keys Input Array(*) of Binary(4)



The Retrieve Service Attributes (QESRSRVA) API copies specified service attributes into the receiver

variable.


None.


Receiver variable

OUTPUT; CHAR(*)

The variable in which this API returns the data. See “Receiver Variable Format” on page 139.


INPUT; BINARY(4)


#TOP_OF_PAGE

aplist.htm

The length of the receiver variable. The length of the receiver variable is 16 times the number of

service attributes to be retrieved, plus the length of each service attribute retrieved, plus 4.

As an example, the size of the receiver variable needed to retrieve the automatic problem analysis

and automatic problem reporting attributes is (16 * 2) + 1 + 1 + 4.

Note: If this value is larger than the actual size of the receiver variable, the results may not be

predictable.

Number of service attribute keys

INPUT; BINARY(4)

The total number of service attributes to retrieve.

Service attribute keys

INPUT: ARRAY(*) of BINARY(4)

A list of keys that identify which service attributes to retrieve. The keys and their associated

service attributes are:

Key Service attribute

1 Automatic problem analysis

2 Automatic problem reporting

3 Service provider to report problem

4 PTF install type

5 Critical message recipients

6 Send data packets

7 Copy PTFs

8 PTF group levels

9 ECS message queue

10 System-disabled reporting connection number

11 System-disabled call-back connection number

12 Service provider connection number

Error code

I/O; CHAR(*)


parameter.

Receiver Variable Format

The format of the receiver variable follows.

Offset

Type Field Dec Hex

0 0 BINARY(4) Number of service attributes retrieved

4 4 ARRAY(*) of

BINARY(4)

Offsets to service attribute templates

* * CHAR(*) Service attribute templates


Field Descriptions

Number of service attributes retrieved.

The number of service attributes the API put into the receiver variable. This number will be less than the

number requested if the receiver variable is too small.

Offsets to service attribute templates. A list of values. Each value is an offset from the beginning of the

receiver variable to a service attribute template.

Service attribute templates. The templates of the requested service attributes. There is one template for

each service attribute retrieved. The formats of the templates are shown in “Service Attribute Template

Format.”

Service Attribute Template Format

The format of a service attribute template follows.

Offset

Type Field Dec Hex

0 0 BINARY(4) Service attribute key

4 4 CHAR(1) Data type of service attribute

5 5 CHAR(1) Status of service attribute


8 8 BINARY(4) Length of service attribute

12 C CHAR(*) Service attribute

Field Descriptions

Data type of service attribute. The type of data returned.

0 The service attribute was not available.

1 The service attribute is returned in character format.

2 The service attribute is returned in binary format.

Length of service attribute. The length of the service attribute. If the service attribute was not available,

this value is 0.

Reserved. This field will contain null characters.

Service attribute. The requested service attribute. See “Service Attributes Format” on page 141 for the

formats of the service attributes.

Service attribute key. A value that identifies the service attribute that was retrieved.

Status of service attribute. Whether the service attribute was available for retrieval.

0 The service attribute was available.

1 The service attribute was locked.


Service Attributes Format

The Service Attributes Format has the following self-explanatory keys to solve problems:

v “Key 1—Automatic Problem Analysis”

v “Key 2—Automatic Problem Reporting”

v “Key 3—Service Provider to Report Problem” on page 142

v “Key 4—PTF Install Type” on page 142

v “Key 5—Critical Message Recipients” on page 142

v “Key 6—Send Data Packets” on page 143

v “Key 7—Copy PTFs” on page 143

v

Key 8—PTF group levels (page “Key 8—PTF group levels” on page 144)

v “Key 9—ECS message queue” on page 144

v “Key 10—System-Disabled Reporting Connection Number” on page 144

v “Key 11—System-Disabled Call-Back Connection Number” on page 144

v “Key 12—Service Provider Connection Number” on page 145

Key 1—Automatic Problem Analysis

Offset

Type Field Dec Hex

0 0 CHAR(1) Attribute

Field Descriptions

Attribute. The problem analysis attribute specifies when to analyze problems.

0 Problems will not be analyzed when they are logged. Instead, the operator must analyze the problem from

the QSYSOPR message queue or from the Work with Problems (WRKPRB) command.

1 The system will analyze the problem as soon as the problem is logged.

Key 2—Automatic Problem Reporting

Offset

Type Field Dec Hex


Field Descriptions

Attribute. The problem reporting attribute specifies when to report problems.

0 Problems will not be reported when they are logged. Instead, the operator must report the problem from the

QSYSOPR message queue or from the Work with Problems (WRKPRB) command.

1 If the problem analysis attribute specifies that problems are to be analyzed as soon as the problem is logged,

the system will report the problem to the service provider specified in the Service provider to report problem

attribute as soon as the problem is analyzed.


Key 3—Service Provider to Report Problem

Offset

Type Field Dec Hex

0 0 CHAR(1) Name format

1 1 CHAR(17) Service provider name

Field Descriptions

Name format. This is an ’A’ to show that the name is an SNA node name.

Service provider name. This identifies the service provider to report problems to if the automatic

problem reporting’ attribute specifies that problems are to be reported as soon as a problem is analyzed.

If this field contains *IBMSRV, problems will be sent to IBM. Otherwise, the first eight characters of this

field contain the control point name of the service provider. The next nine characters contain either the

network identifier of the service provider, or *LCLNETID if the network identifier of the service provider

is the same as that of the system that is reporting the problem.

Key 4—PTF Install Type

Offset

Type Field Dec Hex

0 0 CHAR(10) Type of PTF install

Field Descriptions

Type of PTF install. This service attribute determines whether the immediate PTFs are applied

immediately or delayed.

*DLYIPL All PTFs will be marked for delayed apply and the system will be IPLed.

*DLYALL All PTFs will be marked for delayed apply and the system will not be IPLed.

*IMMONLY The immediate PTFs will be applied and the delayed PTFs marked for apply at the next IPL.

*IMMDLY Only the immediate PTFs will be applied and the system will not be IPLed.

Key 5—Critical Message Recipients

Offset

Type Field Dec Hex

0 0 BINARY(4) Number of entries

4 4 ARRAY(50) of

CHAR(10)

User list

Field Descriptions

Number of entries. This is the number of entries in the user list.

User list. This is an ordered list of user identifiers and user classes. If the system detects a critical

condition such as a disk failure, and the first entry in this list is a user identifier, and that user is signed


on, the system will send a break message to that user. If the first entry is a user class, the system will try

to send a break message to all the users in that class that are signed on.

If the specified user is not signed on, or none of the users in the user class are signed on, the system tries

to send the break message to the user identifier or user class in the second entry of this list.

The system keeps trying to find a user that is signed on until it reaches the end of the list.

This function is only used if problem analysis routines are run automatically at the time of failure (the

ANZPRBAUTO service attribute is *YES).

*SYSOPR All users of user class *SYSOPR will receive a message when a critical message is sent.

*SECOFR All users of user class *SECOFR will receive a message when a critical message is sent.

*SECADM All users of user class *SECADM will receive a message when a critical message is sent.

*PGMR All users of user class *PGMR will receive a message when a critical message is sent.

*USER All users of user class *USER will receive a message when a critical message is sent.

Key 6—Send Data Packets

Offset

Type Field Dec Hex


Field Descriptions

Attribute. The Send data packets attribute specifies whether or not to send problem data to the service

provider.

0 Data will not be sent to the service provider.

1 Up to 2000 bytes of data will be sent to the service provider.

Key 7—Copy PTFs

Offset

Type Field Dec Hex


Field Descriptions

Attribute. The Copy PTFs attribute specifies whether or not to copy PTF save files and cover letters into

*SERVICE when PTFs are loaded from a tape or optical device. PTF save files must be in *SERVICE when

distributing PTFs to other systems or when using the Save System Information (SAVSYSINF) command.

0 PTF save files and cover letters are not copied into *SERVICE when PTFs are loaded from tape or optical.

1 PTF save files and cover letters that do not already exist are copied into *SERVICE when PTFs are loaded

from tape or optical.


Key 8—PTF group levels

Offset

Type Field Dec Hex

0 0 BINARY(4) Attribute

Field Descriptions

Attribute. The PTF group levels attribute specifies the maximum number of levels of a PTF group to

keep on the system. The following special value can be returned:

-1 Specifies that all levels should be kept on the system.

Key 9—ECS message queue

Offset

Type Field Dec Hex

0 0 CHAR(10) ECS message queue

10 A CHAR(10) Library

Field Descriptions

ECS message queue. The message queue name where electronic customer support (ECS) will be sending

the message when resuming PTF orders.

Library. The library where the message queue is located.

Key 10—System-Disabled Reporting Connection Number

Offset

Type Field Dec Hex

0 0 CHAR(30) System-disabled reporting connection number

Field Descriptions

System-disabled reporting connection number. The complete electronic connection number used for

automatic reporting to external support when this system is disabled. This number should include the

entire sequence of numbers required to complete the call, including international access codes, country or

region codes, area codes, exchanges, and so on, as appropriate.

Key 11—System-Disabled Call-Back Connection Number

Offset

Type Field Dec Hex

0 0 CHAR(30) System-disabled call-back connection number


Field Descriptions

System-disabled call-back connection number. The complete electronic connection number used to call

back this system from external support when this system is disabled. This number should include the

entire sequence of numbers required to complete the call, including international access codes, country or

region codes, area codes, exchanges, and so on, as appropriate.

Key 12—Service Provider Connection Number

Offset

Type Field Dec Hex

0 0 CHAR(30) Service provider connection number

Field Descriptions

Service provider connection number. The complete electronic connection number to the service provider.

This number should include the entire sequence of numbers required to complete the call, including

international access codes, country or region codes, area codes, exchanges, and so on, as appropriate.

Error Messages


CPF24B4 E Severe error while addressing parameter list.

CPF3C19 E Error occurred with receiver variable specified.



CPF8C50 E Key in input list not valid.

CPF8C51 E Error with receiver variable length.

CPF8C52 E Number of values in input list not valid.




Retrieve XML Service Information (QSCRXMLI) API


1 Destination information Input Char(*)

2 Destination format name Input Char(8)


4 Receiver format name Input Char(8)

5 Service selection

information

Input Char(*)

6 Service selection

information format

Input Char(8)




#TOP_OF_PAGE

aplist.htm

The Retrieve XML Service Information (QSCRXMLI) API lists service information, such as messages

from a nonprogram message queue, messages sent to the program message queue of a job,

or

messages sent to the history log

, in XML format, and optionally stores the output in a stream file.

New messages are prevented from being added to or removed from the message queue listed during the

use of the QSCRXMLI API.

See the Open List of Messages (QGYOLMSG) API, Open List of Job Log Messages (QGYOLJBL) API,

or Open List of History Log Messages (QMHOLHST) API

for the description of the message fields

returned.


Output File Authority (if output stored in a stream file)

Authority to the path and file are determined by the open() API. For details, see the Authorities

section of the open()—Open File API for files opened with an access mode of O_WRONLY and

O_TRUNC.

Output File Lock

*SHRNUP

Message Queue

*USE

Message Queue Library

*EXECUTE

User Space Lock

*EXCLRD

Job Authority

v *JOBCTL special authority if the job for which messages are being listed has a different user

profile from that of the job that calls the QSCRXMLI API.

v *ALLOBJ and *JOBCTL special authorities if the job for which messages are being retrieved has

*ALLOBJ and *JOBCTL special authority. As an alternative to having *ALLOBJ authority, the

user that calls the API can be authorized to the All Object Job Log function of the i5/OS®

operating system through System i™ Navigator’s Application Administration support. The

Change Function Usage (CHGFCNUSG) command, with a function ID of

QIBM_ACCESS_ALLOBJ_JOBLOG, can also be used to change the list of users that are allowed

to access a job log that has *ALLOBJ special authority.

For additional information on job authorities, see Plan and set up system security.


Destination information

INPUT; CHAR(*)

Provides information about the destination for the generated XML output.

v If DEST0100 is specified for the destination format name, this parameter contains a 4-byte

integer which is the size of the receiver variable (parameter 3).

v If DEST0200 is specified for the destination format name, this parameter contains a structure

which gives the path name of the stream file where the generated XML output is to be stored.

Destination format name

INPUT; CHAR(8)

The destination format to determine where the generated XML output will be stored. Possible

values are:


open.htm

“DEST0100 Format” Return the XML output in the receiver variable.

“DEST0200 Format” on page

148

Return the XML output in a stream file using the path name coded in the destination

information parameter.

Receiver variable

OUTPUT; CHAR(*)

The variable that is to receive the generated XML output. The variable is used only when the

destination format name is DEST0100. If the receiver variable is not large enough to hold all of

the generated XML output, no XML output is returned.

Receiver format name

INPUT; CHAR(8)

The format of the generated XML output to be returned. You must use one of the following

format names:

“SIRV0100 Format” on page

148

The information returned to the caller of this API. For more information, see

“SIRV0100 Format” on page 148.

Service selection information

INPUT; CHAR(*)

The information that identifies the source of the service information to be returned. The format of

this information depends on the specified Service selection format name.

Service selection format name

INPUT; CHAR(8)

Indicates where the service information will be retrieved from. The possible values are:

“SSIF0100 Service Selection

Information from a

Nonprogram Message Queue

Format” on page 148

The list of messages will be retrieved from a nonprogram message queue as specified

in “SSIF0100 Service Selection Information from a Nonprogram Message Queue

Format” on page 148.

“SSIF0200 Service Selection

Information from a Program

Message Queue of a Job

Format” on page 149

The list of messages will be retrieved from a program message queue of a job as

specified in “SSIF0200 Service Selection Information from a Program Message Queue

of a Job Format” on page 149.

SSIF0300 (page “SSIF0300

Service Selection Information

from the History Log” on page

149)

The list of messages will be retrieved from the History Log as specified in SSIF0300

Service Selection Information from the History Log (page “SSIF0300 Service Selection

Information from the History Log” on page 149).

Error code

I/O; CHAR(*)


parameter.

DEST0100 Format

The following information needs to be supplied in the destination information parameter (parameter 1)

for the DEST0100 format.

Offset

Type Field Dec Hex

0 0 BINARY(4) Length of receiver variable


Field Descriptions

Length of receiver variable. The length of the receiver variable. If the length is larger than the size of the

receiver variable, the results may not be predictable. The minimum length is 8 bytes.

DEST0200 Format

The destination information parameter (parameter 1) specifies the file path name where the generated

XML output is to be returned for the DEST0200 format. See Path name format for information on

specifying the output stream file path name.

SIRV0100 Format

The following information is returned in the receiver variable for the DEST0100 format.

Offset

Type Field Dec Hex

0 0 BINARY(4) Bytes returned

4 4 BINARY(4) Bytes available

8 8 BINARY(4) XML data length

12 C CHAR(*) XML data

Field Descriptions




XML data. The XML output of the service information returned. If the receiver variable is not large

enough to hold the entire XML output or if an unexpected error occurs while writing to the receiver

variable, no data will be returned.

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

SSIF0100 Service Selection Information from a Nonprogram Message

Queue Format

Offset

Type Field Dec Hex

0 0 CHAR(10) Message queue name

10 0A CHAR(10) Message queue library

Field Descriptions

Message queue library. The name of the library where the message queue is located.

Message queue name. The name of the message queue whose messages are to be listed.


SSIF0200 Service Selection Information from a Program Message

Queue of a Job Format

Offset

Type Field Dec Hex

0 0 CHAR(26) Qualified job name

Field Descriptions

Qualified job name. The name of the job whose messages are to be listed. The qualified job name has

three parts:

Job name CHAR(10)A specific job name or one of the following special value:

* The job that this program is running in. The rest of the qualified job name parameter

must be blank.

User name CHAR(10) A specific user profile name, or blanks when the job name is the special value of *.

Job number CHAR(6) A specific job number, or blanks when the job name is the special value of *.

SSIF0300 Service Selection Information from the History Log

Offset

Type Field Dec Hex

0 0 BINARY(4) Length of the fixed portion of the information

4 4 CHAR(10) Start date

14 E CHAR(10) Start time

24 18 CHAR(6) Start after time microseconds

30 1E CHAR(10) End by date

40 28 CHAR(10) End by time

50 32 CHAR(6) End by time microseconds

56 38 BINARY(4) Message ids list contents indicator

60 3C BINARY(4) Offset to list of message ids

64 40 BINARY(4) Number of messages ids in list

68 44 BINARY(4) Offset to jobs to list

72 48 BINARY(4) Number of jobs to list

76 4C BINARY(4) Message severity

80 50 BINARY(4) Message types list contents indicator

84 54 BINARY(4) Offset to list of message types

88 58 BINARY(4) Number of message types in list

92 5C CHAR(*) Reserved

* * CHAR(*) Message ids list

* * CHAR(*) Jobs to list

* * CHAR(*) Message types list


Field Descriptions

End by date. Specifies the ending date for messages and jobs to be listed. If blank, *END will be used.

One of the following is used to specify the ending date before which or on which the data must have

been logged.

*CURRENT

The current day is the last day for which logged data is listed.

*END The last day on which data was logged is the last day for which the logged data is listed. If

*END is specified, an ending time value other than *AVAIL is ignored.

end-date

The format of this field is in CYYMMDD as follows, with the last 3 bytes of the field ignored:

C Century, where 0 indicates years 19xx and 1 indicates

years 20xx.

YY Year

MM Month

DD Day

End by time. Specifies the ending time for messages and jobs to be listed. If blank, *AVAIL will be used.

One of the following is used to specify the ending time before which the data must have been logged.

*AVAIL

Any logged data that is available for the specified ending date is listed.

end-time

Specify the ending time for the specified ending date that indicates the logged data to be listed.

The time is specified in 24-hour format and the format of this field is in the HHMMSS as follows,

with the last 4 bytes of the field ignored:

HH Hour

MM Minute

SS Second

End by time microseconds. Specifies the ending times microseconds. Messages will be listed up to and

including this time if available. If blank, 0 will be used.

Jobs to list. Specifies the specific jobs (if any) for which messages in the log are listed. The messages for

the specified jobs are retrieved only if they were logged in the period of time, message severity, message

types and messages specified on the call. If the offset and number of jobs to list are 0 all available jobs

will be listed.

A job name can be qualified with up to three elements.

v job-name

v user-name/job-name

v job-number/user-name/job-name

Any other qualifications would result in all jobs being listed. For example, if a user-name was listed with

blanks for the job-name and job-number then the job data would be ignored and all jobs would be

returned.


Format of the Jobs to list:

These fields repeat for each job specified. CHAR(10) Job name

CHAR(10) User name

CHAR(6) Job number

If a job name is not qualified with a user name and number, all jobs by that name in the log, within the

selection will have their messages returned. Use blanks for the job-number or user-name if the job-name

is to be listed for all job-number/user-names. Up to 5 jobs are supported.

Length of the fixed portion of the information. Specifies the length of the fixed portion of the selection

information. It must be set to 92.

Message IDs list. Specifies the specific message IDs to be retrieved or omitted. Up to 100 message IDs

are supported. If not specified, all of the messages will be listed for the jobs, message severity, message

types and times specified. If the offset list contents indicator and number message IDs are 0 all available

messages will be listed. To select specific generic types of messages, specify the 3-character code that

identifies the message file followed by all zeros. For example, CPF0000 specifies that all CPF messages

that meet the specifications of the previous parameters are selected or omitted. If an identifier is specified

as pppnn00, any message beginning with the specified five characters (pppnn) can be selected or omitted.

Format of Message IDs list:

This field repeats for each message ID specified. Char(7) Message ID

Message IDs list contents indicator. Specifies if the messages IDs in the list are to be omitted or selected.

To omit the message ids in the list set this field to 1. To select the message ids in the list set this field to 0.

If not specified, 0 will be used.

Message severity. The minimum severity of the messages to be listed. Possible values are 0 through 99.

Specify 0 to list all messages for the jobs, times, message types and message ids specified. If not specified,

0 will be used.

Message types list. Specifies the specific message types to be retrieved or omitted. Up to 10 message

types are supported. If not specified all of the messages will be listed for the jobs, message severity and

times specified. If the offset and number of message types are 0, all available message types will be listed.

Format of Message types list:

This field repeats for each message type specified. Char(10) Message type

Valid message type values and their meanings follow:

Value Message type

*COMP Completion

*COPY Copy

*DIAG Diagnostic

*ESCAPE Escape

*INFO Informational

*INQ Inquiry

*NOTIFY Notify


Value Message type

*RPY Reply

*RQS Request

Message types list contents indicator. Specifies if the message types in the list are to be omitted or

selected. To omit the message types in the list set this field to 1. To select the message types in the list set

this field to 0. If not specified, 0 will be used.

Number of jobs to list. Specifies the number of jobs to list. Specifying 0 for this field will list all jobs

available for the time, message severity, message types and message ids specified. A maximum of 5 jobs

can be specified. If the number of jobs to list does not match the number of jobs specified unpredictable

results may occur. If not specified, 0 will be used.

Number of message IDs in list. Specifies the number of message ids in the list. Specifying 0 for this field

will list all messages available for the time, jobs, message types and severity level specified. A maximum

of 100 message ids can be specified. If the number of message ids in list does not match the message ids

in the list unpredictable results may occur. If not specified, 0 will be used.

Number of message types in list. Specifies the number of message types in the list. Specifying 0 for this

field will list all message types available for the time, jobs, message ids and severity level specified. A

maximum of 9 message types can be specified. If the number of message types in list does not match the

message types in the list unpredictable results may occur. If not specified, 0 will be used.

Offset to jobs to list. The offset, in bytes, from the beginning of the message selection information format

to the beginning of the jobs to list entry. Specifying 0 for this field and number of jobs to list will list all

jobs available for the time, message severity, message types and message ids specified. If this is set to 0,

the number of jobs to list must also be set to 0. If not specified, 0 will be used.

Offset to list of message IDs. The offset, in bytes, from the beginning of the message selection

information format to the beginning of the message ids list entry. Specifying 0 for this field, message IDs

list contents indicator and number of message IDs in list will list all messages available for the time,

message severity, message types and jobs to list specified. If this is set to 0, the number of message ids in

list must also be set to 0. If not specified, 0 will be used.

Offset to list of message types. The offset, in bytes, from the beginning of the message selection

information format to the beginning of the message types list entry. Specifying 0 for this field, message

types list contents indicator and number of message types in list will list all message types available for

the time, message IDs, message severity and jobs to list specified. If this is set to 0 the number of

message types in list must also be set to 0. If not specified, 0 will be used.

Reserved. An ignored field.

Start date. Specifies the starting date for messages and jobs to be listed. If not specified, *CURRENT will

be used.

One of the following is used to specify the starting date on which or after which the data must have been

logged. Any entries logged before the specified date are not listed.

*CURRENT

The logged data for the current day and between the specified starting and ending times (if

specified) is listed.

*BEGIN

The logged data from the beginning of the log is listed.


start-date

The format of this field is in the CYYMMDD as follows, with the last 3 bytes of the field ignored:

C Century, where 0 indicates years 19xx and 1 indicates

years 20xx.

YY Year

MM Month

DD Day

Start time. Specifies the starting time for messages and jobs to be listed. If not specified, *AVAIL will be

used.

One of the following is used to specify the starting time at which or after which the data must have been

logged. Any entries logged before the specified time and date are not listed.

*AVAIL

Any logged data that is available for the specified starting date is listed.

start-time

Specify the starting time for the specified starting date that indicates the logged data to be listed.

The time is specified in 24-hour format and the format of this field is in the HHMMSS as follows,

with the last 4 bytes of the field ignored:

HH Hour

MM Minute

SS Second

Start after time microseconds. Specifies the starting times microseconds to be used. The messages listed

will be listed after this time. If blank, 0 will be used.

Usage Notes

The output file path name is represented by the ’Path name’ field in the ’Path Name Format’ structure

when using the DEST0200 destination format. The output file path name is used to store the generated

XML output. The output stream file is opened for writing only, in text-only mode, in CCSID 1208, and

allows sharing with readers only. If the output stream file exists, the file is truncated to zero length before

writing any data. If the output stream file already exists, it should have been created with a CCSID of

1208; otherwise, the resulting XML output may not be usable. If the output file does not exist, it will be

created with a CCSID of 1208 before attempting to write the XML output to it. The output file is created

so that the file owner has read and write permission to it. The output file can be replaced if the user has

the authority to do so. For more information on authority requirements for stream files, see the

open()—Open File API in the Integrated File System section of the APIs in the Information Center.

Error Messages



CPE3006 E Input/output error.

CPE3014 E The object name is not correct.

CPE3021 E The value specified for the argument is not correct.

CPE3025 E No such path or directory.

CPE3027 E Operation not permitted.

CPE3029 E Resource busy.

CPE3401 E Permission denied.


open.htm


CPE3403 E Not a directory.

CPE3404 E No space available.

CPE3406 E Operation would have caused the process to be suspended.

CPE3407 E Interrupted function call.

CPE3408 E The address used for an argument was not correct.

CPE3436 E There is not enough buffer space for the requested operation.

CPE3440 E Operation not supported.

CPE3450 E Descriptor not valid.

CPE3452 E Too many open files for this process.

CPE3453 E Too many open files in the system.

CPE3460 E Storage allocation request failed.

CPE3470 E Function not implemented.

CPE3471 E Specified target is a directory.

CPE3474 E Unknown system state.

CPE3484 E A damaged object was encountered.

CPE3485 E A loop exists in the symbolic links.

CPE3486 E A path name is too long.

CPE3489 E System resources not available to complete request.

CPE3490 E Conversion error.

CPE3499 E Object is suspended.

CPE3500 E Object is a read only object.

CPE3507 E Object too large.

CPE3511 E File ID conversion of a directory failed.

CPE3512 E A File ID could not be assigned when linking an object to directory.

CPE3513 E File handle rejected by server.

CPE3524 E Function not allowed.

CPFA09E E Object in use. Object is &1.

CPF2207 E Not authorized to use object &1 in library &3 type *&2.

CPF24B4 E Severe error while addressing parameter list.

CPF2401 E Not authorized to library &1.

CPF2403 E Message queue &1 in &2 not found.

CPF2408 E Not authorized to message queue &1.

CPF2433 E Function not allowed for system log message queue &1.

CPF2441 E Not authorized to display job log.

CPF2443 E Job log not displayed or listed because job has ended.

CPF2447 E No entries exist in current version of log.

CPF2480 E Requested version of log damaged.

CPF2499 E Message identifier &1 not allowed.

CPF2519 E Error occurred while processing message ID list.


CPF3C19 E Error occurred with receiver variable specified.

CPF3C21 E Format name &1 is not valid.

CPF3C53 E Job &3/&2/&1 not found.

CPF3C55 E Job &3/&2/&1 does not exist.

CPF3C58 E Job name specified is not valid.


CPF6565 E User profile storage limit exceeded.

CPF8100 E All CPF81xx messages could be returned. xx is from 01 to FF.

CPF9801 E Object &2 in library &3 not found.

CPF9803 E Cannot allocate object &2 in library &3.



CPF2403 E Message queue &1 in &2 not found.

CPF2408 E Not authorized to message queue &1.



CPF2433 E Function not allowed for system log message queue &1.



Send Service Request (QPDETSND) API


1 Request Data Input Char(*)

2 Length of request data Input Binary(4)

3 Format or request data Input Char(8)


Default Public Authority:

*EXCLUDE

Threadsafe: No

The Send Service Request (QPDETSND) API sends the request to the Service Monitor or to the Service

Control job.

If the Service Control job is not active, the job will be submitted.

If the Service Monitor is not active, and the request is for a Service Monitor function, a request will be

submitted to the Service Control job to start the Service Monitor before sending the request.



*SERVICE When format SNDR0100 (Refresh policy file request) is sent.


Request data

INPUT; CHAR(*)

Information to use while processing the request. The format of this data is specified by the

Format of request data parameter.

Length of request data

INPUT; BINARY(4)

How long the request data is.

Format of request data. This indicates the type of request being submitted. Only the following values

are accepted:

INPUT; CHAR(8)

“SNDR0100 - Refresh Policy File Request” on page 156 Send a refresh Service Monitor policy file

request.

“SNDR0200 - Start a Function Request” on page 156 Send a start function request.


#TOP_OF_PAGE

aplist.htm

“SNDR0300 - Stop a Function Request” Send a stop function request.

“SNDR0400 - Service Event Request” Send a Service event request.

“SNDR0500 - Change Logging Levels Request” on page 157 Send a change logging level request.

“SNDR0600 - Handle Changed System Value Request” on page 157 Send a handle changed system

value request.

Error code

I/O; CHAR(*)


parameter.

SNDR0100 - Refresh Policy File Request

Offset

Type Field Dec Hex

0 0 BINARY(4) Type of policy data

4 4 BINARY(4) Length of policy data

8 8 CHAR(*) Policy data

SNDR0200 - Start a Function Request

Offset

Type Field Dec Hex

0 0 BINARY(4) Number of functions to start

4 4 Array of BIN(4) Functions to start

SNDR0300 - Stop a Function Request

Offset

Type Field Dec Hex

0 0 BINARY(4) Number of functios to stop

4 4 Array of BIN(4) Functions to stop

SNDR0400 - Service Event Request

Offset

Type Field Dec Hex

0 0 BINARY(4) Length of header information

4 4 BINARY(4) Offset to service event

8 8 BINARY(4) Length of service event data

12 C CHAR(10) Service event type

22 16 CHAR(10) Service event identifier

32 20 CHAR(10) Service event error detection


Offset

Type Field Dec Hex

42 2A CHAR(*) Service event data

SNDR0500 - Change Logging Levels Request

Offset

Type Field Dec Hex

0 0 BINARY(4) Logging Level

SNDR0600 - Handle Changed System Value Request

Offset

Type Field Dec Hex

0 0 BINARY(4) Number of system values changed

4 4 Array of CHAR(10) System Value names

Field Descriptions

Functions to start. An array of BINARY(4) values. Each value indicates a particular function to start.

Supported values are:

1 Start the Service Monitor function

2 Start the Communications Trace Analyzer Function

Functions to stop. An array of BINARY(4) values. Each value indicates a particular function to stop.

Supported values are:

1 Stop the Service Monitor function

2 Stop the Communications Trace Analyzer Function

3 Stop the Service Control function

Length of header information. The length of the fixed portion of the header information. It must be

42.

Length of policy data. The length of the provided data.

Length of service event data. The length of the service event data provided.

Logging level. The logging level of the Service Monitor function. This value should only be used when

requested by IBM Support personnel. This changes the amount of data which the Service Monitor logs

for problem determination reasons. Supported values are:


0 No logging

1 Low logging

2 Medium logging

3 High logging

Number of functions to start. How many functions to start.

Number of functions to stop. How many functions to stop.

Number of system values changed. How many system values where changed.

Offset to service event. The offset to the field that holds the service event request. It must be 36.

Policy data. This data is in schema validated XML format. The location of the XSD file is imbedded

within the XML.

Service event data. Data about the service event being sent. This data is in schema validated XML

format. The location of the XSD file is imbedded within the XML. This format can be generated by using

the “Convert Format of Service Information (QPDETCVT) API” on page 110 with a format name of

CVTS0100 or CVTS0200.

Service event error detection. Indicates who found the error and sending a service request.


*ERROR Error detected by watch exit program. The watch session that was passed in Service event

identifier parameter will be ended.

Blanks No error detected by watch exit program

Service event identifier. The name of the session that is sending a request. If there is not session

identifier, the value should be *NONE

Service event type. Type of event that is sending a request.


*MSGID Message identifier.

*LICLOG LIC log entry.

*PAL PAL entry.

System value names. An array containing the names of the system values that were changed. Supported

values are:

QSFWERRLOG Software Error Logging

Type of policy data. The type of policy data provided. Supported values are:

0 The policy data provided contains the path name to an IFS file containing policy data.

1 The policy data provided contains the actual policy data.


Error Messages




CPF3C1D Input variable length in parameter * not valid.





CPF3C24 Length of receiver variable not valid.

CPF3C39 Value for reserved field not valid.




CPFE083 Service Monitor is not running.

CPFE084 Value Duplicated functions requested.



Set User Policy (QPDETPOL) API


1 Policy data Input Char(*)

2 Length of policy data Input Binary(4)

3 Format of policy data Input Char(8)



The Set User Policy (QPDETPOL) API allows the changing of user policies related to service. This

includes:

v How long to retain service related information

v What level of information to send when the system automatically reports a problem to a service

provider

v What is the maximum size for a PTF order to be delivered electronically

v What is the period of time for duplicate problem processing

v

What is the maximum time for downloading a PTF order.

v What are the preferred actions when reporting a problem.

v What is the period of time for duplicate problem processing.


Special Authority

To use this API, you must have service (*SERVICE) special authority.


#TOP_OF_PAGE

aplist.htm


Policy data

INPUT; CHAR(*)

Information to use when setting the policy.

Length of policy data

INPUT; BINARY(4)

How long the policy data is.

Format of policy data

INPUT; CHAR(8)

Which policy to set. Only the following values are accepted.

“POLS0100 - Format for

setting service interval policy

for Service Monitor cleanup”

Set service cleanup interval policy.


setting the level of problem

documentation sent with a

problem” on page 161

Set problem documentation level.


setting maximum PTF order

size and downloading time” on

page 161

Set maximum PTF order size and downloading time.

POLS0400 (page


setting the period of time for

problem processing” on page

161)

Set period of time for duplicate problem processing.

POLS0500 (page “POLS0500 -

Format for setting preferred

action when reporting a

problem” on page 161)

Set preferred actions when reporting a problem.

Error code

I/O; CHAR(*)


parameter.

POLS0100 - Format for setting service interval policy for Service

Monitor cleanup

The following information needs to be supplied in the policy data parameter (parameter 1) for the

POLS0100 format.

Offset

Type Field Dec Hex

0 0 BINARY(4) Number of days


POLS0200 - Format for setting the level of problem documentation

sent with a problem


POLS0200 format.

Offset

Type Field Dec Hex

0 0 CHAR(10) Problem documentation level

POLS0300 - Format for setting maximum PTF order size and

downloading time


POLS0300 format.

Offset

Type Field Dec Hex

0 0 BINARY(4) Maximum PTF order size over LAN

4 4 BINARY(4) Maximum PTF order size over a modem

8 8 BINARY(4) Maximum time for downloading a PTF order over LAN

12 C BINARY(4) Maximum time for downloading a PTF order over modem

POLS0400 - Format for setting the period of time for problem

processing


POLS0400 format.

Offset

Type Field Dec Hex

0 0 BINARY(4) Time for duplicate problem processing

POLS0500 - Format for setting preferred action when reporting a

problem


POLS0500 format.

Offset

Type Field Dec Hex

0 0 BINARY(4) Number of preferred actions.

4 4 Array of BIN(4) Preferred actions.


Field Descriptions

Maximum PTF order size over a modem. The maximum size in megabytes for a PTF order to be

delivered electronically over a modem. This policy is shipped with a default value of 100 MB (MB equals

approximately 1 000 000 bytes). If -1 is specified, PTF orders of any size are delivered over a modem.

This policy cannot be set to a value less than 100 MB.

Maximum PTF order size over LAN. The maximum size in megabytes for a PTF order to be delivered

electronically over the local area network (LAN). If -1 is specified, PTF orders of any size are delivered

over the LAN. This policy is shipped with a default value of -1. This policy cannot be set to a value less

than 100 MB (MB equals approximately 1 000 000 bytes).

Maximum time for downloading a PTF order over LAN. The maximum time in minutes for

downloading a PTF order over LAN. A value of -1 indicates PTF order can take any time for

downloading the order. This policy is shipped with a default value of -1. This policy cannot be set to a

value less than 30 minutes.

Maximum time for downloading a PTF order over Modem. The maximum time in minutes for

downloading a PTF order over modem. A value of -1 indicates PTF order can take any time for

downloading the order. This policy is shipped with a default value of 60. This policy cannot be set to a

value less than 30 minutes.

Number of days. The number of days an object covered by this policy is allowed to exist before being

deleted by the Service Monitor. Objects covered by this policy are: Service Monitor logs and Integrated

File System files created by the FFDC process. This policy is shipped with a value of 7. This policy cannot

be set to a value less than 1.

Number of preferred actions. The number of preferred actions when reporting a problem.

Preferred actions. Indicates what the preferred actions when reporting a problem are. The following

values are accepted:

0 No preferred action is selected (PTFs are downloaded). This is the default value.

1 Do not download PTFs.

Note: if conflicting preferred actions are encountered then the last setting found in the array determines

the final setting.

Problem documentation level. Indicates how much problem documentation should be included when

problems are automatically reported to the service provider. Only the following values are accepted:

*BASE Minimal documentation is sent in the service request record. No additional data will be

uploaded.

*DEFAULT Minimal documentation will be sent in the service request record. If no fix for the problem is

found, additional documentation will be automatically uploaded. Additional documentation may

include information such as job logs and service dumps.

Time for duplicate problem processing. The number of days to check for duplicate problem to avoid

creating duplicate problem log entries. If a duplicate occurs within the specified number of days, the

existing problem log entry will be updated rather than creating a new problem log entry. If 0 is specified,

duplicate problem checking will not be performed. This policy is shipped with a default value of 30. This

policy cannot be set to a value more than 30 days.


Error Messages



CPFE080 Maximum PTF order size not valid.

CPF0CC1 Error initializing the XML parser.




CPF3C1E Required parameter &1 omitted.


CPF3C3A Value for parameter &2 for API &1 not valid.




Exit Programs

These are the Exit Programs for this category.

Watch for Trace Event Exit Program


1 Trace option setting Input Char(10)

2 Reserved Input Char(10)

3 Error detected Output Char(10)

4 Comparison data Input Char(*)

QSYSINC/H member name: ESCWCHT

The Trace commands such as STRCMNTRC, STRTRC, TRCINT and TRCCNN have the capability to

watch for a specific event and end the trace when this event occurs. An event can be a message being

sent to a specific message queue, history log, job log, LIC log,

or a PAL entry. PAL stands for Product

Activity Log which shows errors that have occurred (such as in disk and tape units, communications, and

work stations).

If specified in the TRCPGM parameter, the watch for trace event facility will call a

user-written program in the circumstances specified in the Trace option setting parameter.


None.


Trace option setting

INPUT; CHAR(10)

The reason indicating the moment at which the user-written program was called. The possible

values are:

*ON The watch for trace facility is starting.


#TOP_OF_PAGE

aplist.htm

*MSGID A match on a message id specified on WCHMSG parameter occurred.

*LICLOG A match on a LIC log specified on the WCHLICLOG parameter occurred.

*CMPDATA The major and minor code of a LIC log matched, but the comparison data did not.

*INTVAL The time interval specified on TRCPGMITV parameter is elapsed.

*WCHTIMO The length of time to watch specified on WCHTIMO is elapsed.

*PAL A match on a PAL and any associated comparison data specified on the WCHPAL parameter

occurred.

Error detected

OUTPUT; CHAR(10)

Indicates if the trace event facility should stop or continue running, or if an error on the

user-written program was found. The possible values are:

*CONTINUE The trace and the watch for trace event facility will continue running

*STOP The trace and the watch for trace event facility will be ended

*ERROR Error detected by customer trace program.

Comparison data

INPUT; CHAR(*)

The format of the trace information depends on the Trace option setting causing the exit program

to be called. The format of the Comparison data is as follows if the Trace option setting is

*MSGID:

Offset

Type Field Dec Hex

0 0 BINARY(4) Length of trace information

4 4 CHAR(7) Message ID




28 1C CHAR(*) Message comparison data

The format of the Comparison data is as follows if the Trace option setting is *LICLOG or

*CMPDATA:

Offset

Type Field Dec Hex


4 4 CHAR(4) LIC Log major code

8 8 CHAR(4) LIC Log minor code

12 C CHAR(8) LIC Log identifier



28 1C CHAR(*) LIC Log comparison data

The format of the Comparison data is as follows if the Trace option setting is *ON, *INTVAL or

*WCHTIMO:


Offset

Type Field Dec Hex

0 0 BINARY(4) Length of trace information (always 4 at this time)

The format of the Comparison data is as follows if the Trace option setting is *PAL:

Offset

Type Field Dec Hex



12 C CHAR(10) Device name

22 16 CHAR(4) Device type

26 1A CHAR(4) Model

30 1E CHAR(15) Serial number

45 2D CHAR(10) Resource name

55 37 CHAR(8) Log identifier

63 3F CHAR(8) PAL timestamp


75 4B CHAR(8) Secondary code

83 53 CHAR(8) Table identifier


92 5C BINARY(4) Sequence





Field Descriptions

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.

Length of trace information. The length of the Comparison data parameter passed to the user-written

exit program.

Length of comparison data. The length of the user specified text to be compared against the event data.

LIC Log identifier. The LIC Log entry identifier of the LIC Log that occurred.

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 comparison data. The user specified text string used to compare against the entry data of the

watched for log entry.


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

Message ID. The identifier of the message that occurred.

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

watched for message ID.

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

Offset to comparison data. The offset to the field that holds the comparison data.

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.

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

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

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.

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.

Related Information

See the following for more information:

v Start Communications Trace (STRCMNTRC) command

v Start Trace (STRTRC) command

v Trace Internal (TRCINT) command

v Trace Connection (TRCCNN) command

Exit program introduced: V5R3

Top | Communications APIs | APIs by category

Concepts

These are the concepts for this category.


#TOP_OF_PAGE

comm.htm

aplist.htm

Key Groups for Problem Log APIs

Key Use for Problem Log APIs

This section describes keys applicable for the following Problem Log APIs:

v QsxAddProblemLogEntry

v QsxChangeProblemLogEntry

v QsxCreateProblemLogEntry

v QsxDeleteProblemLogEntry

v QsxRetrieveProblemLogEntry

Key Utilization Matrix

Key API

Add Change Create Delete Retrieve

Group 0000—General Problem Log Entries

1 Always Always Always Always Always

2 No No Yes No Yes

3 No Yes Yes No Yes

4 No Yes Yes No Yes

5 No No Yes No Yes

6 No Yes Yes No Yes

7 No Yes Yes No Yes

8 Yes Yes Yes No Yes

“Key Group 1000—Problem Description Entries” on page 173

1000 No Yes Yes No Yes















1015 No Yes No No Yes

1016 No Yes No No Yes

“Key Group 2000—FRU Entries” on page 180

2000 No No No Yes Yes


#HDRTG0000

Key API

Add Change Create Delete Retrieve

2001 Yes No Yes No No









“Key Group 3000—Text Entries” on page 186

3000 No No No No Yes


“Key Group 4000-Supporting Data Entries” on page 188




“Key Group 5000—Contact Entries” on page 189



“Key Group 6000—Problem History Entries” on page 191



“Key Group 7000—PTF Entries” on page 192


7001 Yes Yes Yes Yes Yes


“Key Group 8000—Analyzed Error Entries” on page 194


“Key Group 9000—Logical Partition ID Entries” on page 195


Key Group 0000-General Problem Log Entries

This group is required for all problem entries.

This section contains the following keys:

v “Key 1—Problem Log ID” on page 169

v “Key 2—Problem Type” on page 169

v “Key 3—Problem Status” on page 169

v “Key 4—User Assigned” on page 170


v “Key 5—Problem Origin System” on page 170

v “Key 6—Operational Data” on page 171

v “Key 7—Filter Control” on page 172

v “Key 8—Answer Codes” on page 172

For more details about the fields in the following table, see “Field Descriptions for Key Groups for

Problem Log APIs” on page 195.

Key 1—Problem Log ID

Key 1 is required to identify the entry to which data will be added. Key 1 has the following uses:

v Defines whether the problem is being created for a local or remote problem.

v Provides the problem log identifier that is used with the Add, Change, Delete, or Retrieve Problem Log

Entry APIs.

Note: The problem log output parameter provided on the Create Problem Log Entry API is returned in

the key 1 format.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key

4 4 BINARY(4) Key size

8 8 CHAR(31) Problem log identifier


Key 2—Problem Type

This key is used to:

v Define the type of problem log entry.

v Return the type of problem log entry retrieved.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key


8 8 BINARY(4) Problem type. See “Field Descriptions for Key Groups for Problem

Log APIs” on page 195 for a description of the problem types.

Key 3—Problem Status

Defines the status of the problem log. The problem statuses are OPENED, READY, SENT, ANSWERED,

VERIFIED, and CLOSED. PREPARED status implies that the problem log contains data that enables it to

be sent to a service provider. The status is incremental. This means that the problem log entry contains

the minimum level of data required for the problem to achieve such a status. PREPARED may be applied

anytime after a problem has been opened and before it is closed.

Key 6001 is required with this key to record that the problem status has been changed. The status can be

created, changed, or retrieved.


Offset

Type Field Dec Hex

0 0 BINARY(4) Key


8 8 BINARY(4) Problem status

Key 4—User Assigned

Defines to whom the problem has been assigned.

This entry can be created, changed, or retrieved.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key


8 8 CHAR(10) User assigned


Key 5—Problem Origin System

Defines the system on which this problem log entry originated. The system may be local (this system) or

remote (another system). If the Create location field is set to local, the Create Problem Log Entry API

automatically adds the following groups of fields:

v Origin system hardware description

v Origin system operating system

This entry can only be created and retrieved.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key


8 8 BINARY(4) Create location

Note: The following fields Machine type length through Serial number pertain to the origin system hardware

description.

12 C BINARY(4) Machine type length

16 10 BINARY(4) Model length

20 14 BINARY(4) Feature length

24 18 BINARY(4) Serial number length

28 1C CHAR(16) Machine type

44 2C CHAR(16) Model

60 3C CHAR(16) Feature

76 4C CHAR(32) Serial number

Note: The following fields Product ID length through Reserved pertain to the origin system operating system.


Offset

Type Field Dec Hex

108 6C BINARY(4) Product ID length

112 70 BINARY(4) Version length

116 74 BINARY(4) Release level length

120 78 BINARY(4) Modification level length

124 7C CHAR(15) Product ID

139 8B CHAR(5) Version

144 90 CHAR(5) Release level

149 95 CHAR(5) Modification level


156 9C CHAR(13) Create date and time

169 A9 CHAR(2) Delta level

Key 6—Operational Data

This key provides operational information about the problem entry.

All fields, except the Time added field and the When closed fields, can be created, changed, deleted, or

retrieved. The time fields are added automatically by the Create and Change Problem Log Entry APIs,

respectively.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key


8 8 BINARY(4) Key control for key 6

12 C BINARY(4) Creator of entry

16 10 BINARY(4) Alert status

20 14 BINARY(4) Auto PAR

24 18 BINARY(4) Auto notify

28 1C CHAR(10) APAR Library

Note: The following fields Code and Network address are received from the system.

38 26 CHAR(1) Code

39 27 CHAR(20) Network address

Note: The following fields Code and Network address are sent to the system.

59 3B CHAR(1) Code

60 3C CHAR(20) Network address

Note: The following fields Code and Network address are prepared for the system.

80 50 CHAR(1) Code

81 51 CHAR(20) Network address

101 65 CHAR(13) Date and time added

114 72 CHAR(13) Date and time closed


Offset

Type Field Dec Hex

127 7F CHAR(1) Reserved

128 80 BINARY(4) Mode of analysis

Key 7—Filter Control

Offset

Type Field Dec Hex

0 0 BINARY(4) Key


8 8 BINARY(4) Filter event

12 C CHAR(10) Filter name

22 16 CHAR(10) Filter library name

32 20 CHAR(10) Filter group assigned


Key 8—Answer Codes

Contains the answer that was received when the problem was sent to a service provider.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key



12 C BINARY(4) Answer code assigned

16 10 BINARY(4) Answer code returned

20 14 CHAR(5) Problem number

25 19 CHAR(3) Problem branch number

28 1C CHAR(3) Problem country number

31 20 CHAR(10) PTF Order ID


44 2C BINARY(4) Offset to URI 1

48 30 BINARY(4) Length of URI 1

52 34 BINARY(4) Offset to URI 2

56 38 BINARY(4) Length of URI 2

* * CHAR(*) URI information 1

* * CHAR(*) URI information 2


Key Group 1000—Problem Description Entries

This group creates, changes, and retrieves problem description entries.

To locate the key of your need, click one of the following:

v “Key 1001—Problem Severity”

v “Key 1002—Problem Description Message”

v “Key 1003—Problem Creation Data” on page 174

v “Key 1004—Reporting Device” on page 174

v “Key 1005—Failing Resource” on page 175

v “Key 1006—Reporting Code” on page 176

v “Key 1007—Problem Analysis Data” on page 176

v “Key 1008—Fix Verification Status” on page 177

v “Key 1009—Fix Recovery Status” on page 177

v “Key 1010—Symptom String” on page 177

v “Key 1011—PTF Media Selection” on page 178

v “Key 1012—Problem Category” on page 178

v “Key 1013—Client Information” on page 178

v “Key 1014—First Failure Data Capture” on page 179

v “Key 1015—Query Status” on page 180

v “Key 1016—Hardware Location Information” on page 180

Key 1001—Problem Severity

This key defines the impact of the problem on the environment. This key is required for PREPARED

status.

This entry can be created, changed, and retrieved.



Offset

Type Field Dec Hex

0 0 BINARY(4) Key


8 8 BINARY(4) Problem severity

Key 1002—Problem Description Message

This key may be used where a message is used to describe the problem. If a message is not used, use key

3001 (text entry) to provide a description of the problem. Either key 1002 or 3001 is required. This key is

required when the problem type is machine detected. This entry can be created, changed, or retrieved.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key



Offset

Type Field Dec Hex

8 8 CHAR(7) Message identifier

15 F CHAR(10) Message library name

25 19 CHAR(10) Message file name


Key 1003—Problem Creation Data

This is required for machine detected problem types and is optional for other problem types. This entry

can be created, changed, or retrieved.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key


Note: The following fields Reference code through Reference code translate table library are part of the reference

code description data.


10 A CHAR(10) Reference code translate table identifier

20 14 CHAR(10) Reference code translate table library

30 1E CHAR(7) Reference code description message

37 25 CHAR(10) Reference code description file name

47 2F CHAR(10) Reference code description library name

57 39 CHAR(7) Error code message identifier

Key 1004—Reporting Device

This key provides data that defines the machine that contains the failing hardware. This data is required

for a problem to achieve READY status, since it contains the machine that a problem or PTF order will be

reported against.

This entry can be created, changed, or retrieved.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key



Note: The following fields Machine type length through Serial number pertain to the reporting device.

12 C BINARY(4) Machine type length






Offset

Type Field Dec Hex




108 6C CHAR(12) EC number

Key 1005—Failing Resource

This key contains data that defines the object that is failing. Hardware that can fail includes a machine, a

feature, or a component of the machine. To an observer they might appear the same: they both have a

type, a serial number, and a model. The major distinction is whether you have a maintenance contract.

For example, you can report a problem on a tape device 6366, but you cannot report a problem on an

IOP feature number 2615. The 2615 is part of system machine type 9406. A problem can be reported

against 9406 because it has a maintenance contract. This entry can be created, changed, or retrieved.

Where a program object is failing, the product data is also added. Otherwise it must be blank.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key



12 C BINARY(4) Type of hardware

Note: The following fields Machine type length to Serial number pertain to the failing device structure.

16 10 BINARY(4) Machine type length



28 1C BINARY(4) Serial number length

32 20 CHAR(16) Machine type

48 30 CHAR(16) Model

64 40 CHAR(16) Feature

80 50 CHAR(32) Serial number

Note: The following fields Product ID length through Reserved pertain to the failing product structure.

112 70 BINARY(4) Product ID length



124 7C BINARY(4) Modification level length

128 80 CHAR(15) Product ID

143 8F CHAR(5) Version




160 A0 CHAR(4) Instruction


Offset

Type Field Dec Hex

164 A4 CHAR(20) Hierarchy

184 B8 CHAR(10) Resource name

194 C2 CHAR(4) Error log identifier

198 C6 CHAR(10) Program

Key 1006—Reporting Code

Data that defines the program object that is failing or the object against which the problem will be

reported. For example, the licensed internal code of a feature, such as an IOA, is the product on which

the problem will be reported. It is the program object with a maintenance contract.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key



Note: The following fields Product ID length through Reserved pertain to the reporting product description.

12 C BINARY(4) Product ID length









60 3C CHAR(10) Program

70 46 CHAR(4) Probe


Key 1007—Problem Analysis Data

This key contains the post problem analysis results. The reference code description data defines the

program that isolated the error and provides a reference to an object that contains detailed data

describing the failure.

This key is required to move a machine detected problem to READY status. It is optional with other

problem types. The entry can be created, changed, or retrieved.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key



Offset

Type Field Dec Hex

8 8 BINARY(4) Number of times analyzed

12 C BINARY(4) Isolation status

16 10 CHAR(8) PDP

Note: The following fields Reference code through Reference code translate table library pertain to the reference

code description data.


26 1A CHAR(10) Reference code translate table identifier

36 24 CHAR(10) Reference code translate table library

46 2E CHAR(2) Exit point of the PDP

Key 1008—Fix Verification Status

The key that data that defines the status of the verification attempt.

The problem must be in SENT or ANSWERED status to append this data. This entry can be created,

changed, or retrieved.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key


8 8 BINARY(4) Verification status

12 C CHAR(8) PDP

Key 1009—Fix Recovery Status

This key contains data that defines status of the recovery attempt.

The problem must be in SENT or ANSWERED status to append this data. This entry can be created,

changed, or retrieved.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key


8 8 BINARY(4) Recovery status

12 C CHAR(8) PDP

Key 1010—Symptom String

This key contains data that is used to search a data base for the existence of a problem.


The problem must be READY status to append this data. A problem cannot be moved to PREPARED

status without this key. This entry can be created, changed, or retrieved. It is not allowed on problem

type 3, PTF order.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key


8 8 CHAR(256) Symptom

Note: The first character position of this symptom field may not contain a blank.

Key 1011—PTF Media Selection

This key contains data that is used to define the type of media on which a PTF should be delivered. The

type of media is defined by the media type and the machine type on which the media is installed.

Note: If the machine type and model are unknown, zeros must be used for these fields.

A problem cannot be moved to PREPARED status without this key.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key



12 C BINARY(4) Model length

16 10 BINARY(4) Media type



Key 1012—Problem Category

This key contains data that is used to define the category of a problem.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key


8 8 BINARY(4) Problem category

Key 1013—Client Information

This key contains data that defines the failing software on a personal computer.


Offset

Type Field Dec Hex

0 0 BINARY(4) Key


8 8 BINARY(4) Path Name Length

12 C BINARY(4) Product ID length


20 14 BINARY(4) Program Length

24 18 BINARY(4) Function length

28 1C BINARY(4) Client ID length

32 20 BINARY(4) Contact information length

36 24 CHAR(256) Path Name


356 164 CHAR(64) Version

420 1A4 CHAR(64) Program

484 1E4 CHAR(64) Function

548 224 CHAR(256) Client ID

804 324 CHAR(256) Contact information

1060 424 CHAR(20) Address

Key 1014—First Failure Data Capture

This key contains data that is used to indicate the number of times a problem has recurred. The data

contains the program that detected the failure and a description of the product.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key



12 C BINARY(4) Count

16 10 BINARY(4) Object name length

20 14 CHAR(256) Object name

Note: The following fields Product ID length through Reserved pertain to product data.

276 114 BINARY(4) Product ID length


284 11C BINARY(4) Release level length



307 133 CHAR(5) Version


317 13D CHAR(5) Modification level



Key 1015—Query Status

An indicator of the results of a query of the problem log status.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key


8 8 BINARY(4) Query status

Key 1016—Hardware Location Information

This key indicates the physical location of the hardware for frame ID and device locations.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key


8 8 CHAR(4) Frame ID location

12 C CHAR(4) Device location

16 10 CHAR(4) Card location

Key Group 2000—FRU Entries

This key group provides information about field replaceable unit (FRU). This group can only be used

with machine-detected problem types. Keys 2001 through 2009 use a header to define the FRU type,

probability, FRU code, and message identifier for the FRU.

Click one of the following to find your key:

v “Key 2000—Number of FRU Entries to Work with”

v “Key 2001—Device FRU Type” on page 181

v “Key 2002—Code FRU Type” on page 182

v “Key 2003—Media FRU Type” on page 183

v “Key 2004—User FRU Type” on page 183

v “Key 2005—FRU Name” on page 184

v “Key 2006—Attached FRU” on page 184

v “Key 2007—Configuration FRU” on page 185

v “Key 2008—General FRU” on page 185

v “Key 2009—Channel Attached FRU” on page 186

Key 2000—Number of FRU Entries to Work with

This key deletes or retrieves all FRU entries or all FRU entries of a class.




Offset

Type Field Dec Hex

0 0 BINARY(4) Key


8 8 BINARY(4) Class of FRU

12 C BINARY(4) FRU count

Key 2001—Device FRU Type

This defines the data required to create a FRU entry for a device or feature. Device here can also be a

feature code. The device data defines the device or feature.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key


Note: The following fields Class of FRU through Reserved pertain to the FRU header.


12 C BINARY(4) Probability of fix

16 10 CHAR(4) FRU code

20 14 CHAR(7) FRU description message ID


28 1C BINARY(4) Device location text length

32 20 BINARY(4) Coded character set identifier

36 24 BINARY(4) Rack serial number length

Note: The following fields Machine type length through Serial number pertain to device data.


44 2C BINARY(4) Model length





88 58 CHAR(16) Feature

104 68 CHAR(32) Serial number

136 88 CHAR(7) Document reference message ID

143 8F CHAR(256) Device location text

399 18F CHAR(10) Resource name

409 199 CHAR(10) Device name

419 1A3 CHAR(32) Rack serial number

451 1C3 CHAR(2) Card position

453 1C5 CHAR(2) DSA bus number

455 1C7 CHAR(4) Unit address

459 1CB CHAR(2) Port


Offset

Type Field Dec Hex

461 1CD CHAR(3) Reserved

464 1D0 BINARY(4) Device type

Note: The following fields, Transport type through Dependent address 5, pertain to RISC device data.

468 1D4 BINARY(4) Transport type

472 1D8 BINARY(4) Bus number

476 1DC BINARY(4) Card number

480 1E0 BINARY(4) Board number

484 1E4 BINARY(4) Address type

488 1E8 BINARY(4) I/O bus address

492 1EC BINARY(4) Dependent address 2

496 1F0 BINARY(4) Dependent address 3



Key 2002—Code FRU Type

This defines the data required to create a FRU entry for code. Code may be a product, a program, or a

module.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key








Note: The following fields Product ID length through Reserved pertain to product data.










76 4C CHAR(4) Primary function group

80 50 CHAR(4) Secondary function group


Offset

Type Field Dec Hex

84 54 CHAR(10) Module name

94 5E CHAR(7) Document reference message ID


Key 2003—Media FRU Type

This defines the data required to create a FRU entry for media. The device data defines the device on

which the media, such as tape or diskette, was installed.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key








Note: The following fields Machine length type through Serial number pertain to the device data.

28 1C BINARY(4) Machine type length








124 7C CHAR(7) Document reference message ID

131 83 CHAR(10) Resource name

141 8D CHAR(8) Volume ID


Key 2004—User FRU Type

This defines the data required to define a problem resulting from a user action.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key



Offset

Type Field Dec Hex









Key 2005—FRU Name

This defines the data required to create a list of up to six parts that could be failing. The parts are

identified by their part numbers and location.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key









35 23 CHAR(25) Part location

60 3C CHAR(6)(12) Part number array

Key 2006—Attached FRU

This defines the data required to create a list of up to six parts that could be failing. The parts are

identified by their part numbers and location.

This FRU defines parts that are attached to I/O adapters or I/O processors.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key






Offset

Type Field Dec Hex





35 23 CHAR(25) Part location

60 3C CHAR(6)(12) Part number array

Key 2007—Configuration FRU

This key defines an error in the configuration of a device. It provides the name of a panel that may be

displayed defining a problem.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key








28 1C BINARY(4) Coded character set identifier

32 20 BINARY(4) Replacement text length

36 24 CHAR(8) Screen identifier

44 2C CHAR(30) Replacement text


Key 2008—General FRU

This defines a FRU that is not of one of the other classes of FRUs. It provides the name of a panel that

may be displayed defining a problem.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key



28 1C BINARY(4) Class of FRU

32 20 BINARY(4) Probability of fix



Offset

Type Field Dec Hex


47 2F CHAR(1) Reserved


52 34 BINARY(4) Replacement text length

56 38 CHAR(8) Screen identifier

64 40 CHAR(30) Replacement text


Key 2009—Channel Attached FRU

Offset

Type Field Dec Hex

0 0 BINARY(4) Key









35 23 CHAR(4) Fault symptom code

39 27 CHAR(32) Sense bytes


Key Group 3000—Text Entries

This key group creates, retrieves, and changes problem text entries. It provides access to text that defines,

describes, or tracks a problem.

To get to the key of your need, click one of the following:

v “Key 3000—Text Entry”

v “Key 3001—Text Entry” on page 187

Key 3000—Text Entry

Retrieves text about a problem. Either all text associated with the problem or specified text can be

retrieved. The text types associated with the problem are:

v 80 character title, limit to one entry

This entry provides users with a means of describing a problem in their own words. This appears on

the problem list panel.

v Long problem description.


A detailed description of the problem.

v Problem status

Used to provide a means of tracking a problem until it is resolved, especially tracking what the

support organization is doing to resolve the problem.

v Private notes

Provides an area to keep notes about a problem that will not be made public. These notes are not sent

to another system.

v Associated problem data

This area is for general use and can be tailored to the needs of the users.



Offset

Type Field Dec Hex

0 0 BINARY(4) Key


8 8 BINARY(4) Text type

12 C BINARY(4) Text count

Key 3001—Text Entry

Allows the user to create or change data about a problem. The user is responsible for the content and

format.

To create a text entry, provide the length of text to add. The text is referenced by a pointer and the coded

character set identifier. A pointer, defined in key 3001 (Text entry), points to the beginning of the data.

To change the data, a retrieve, although not required, should be performed first. Data provided on the

change API overlays the data previously in the entry. The data is changed by providing the data as done

in a create. To effectively delete the data set, set Text length to 0. This entry can be created, changed, or

retrieved.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key


8 8 BINARY(4) Text type

12 C BINARY(4) Coded character set identifier

16 10 BINARY(4) Text length


32 20 POINTER(SPP) Pointer to the text


Key Group 4000-Supporting Data Entries

This key group maintains a list of files that contain supplemental data about a problem. The data is

contained in spooled or database files. The name and location of the files is maintained by this key

group.

To get to the key of your need, click one of the following:

v “Key 4000—Supporting Data Entries”

v “Key 4001—Spooled File Data”

v “Key 4002—File Data” on page 189

Key 4000—Supporting Data Entries

This key retrieves and deletes all entries or all entries of a type, spooled or database files, associated with

a specific problem. Spooled files are processed using key 4001 and database files are processed using key

4002. Deleting a specific entry is not supported. This entry can be used by the delete and retrieve API.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key


8 8 BINARY(4) File type

12 C BINARY(4) File count

Key 4001—Spooled File Data

This key contains the name of a spooled file that is associated with the problem log entry.

This key is used to add or create an entry. It is also used to return the results of a retrieve operation.

To add or create an entry, use this key to define each spooled file to be associated with the problem. New

entries are added to the file.

To change an entry it must be deleted first then a new one added.

A retrieve is done by passing key 4000 and defining type 1. All spooled file entries are returned, a key

4001 (spooled file data) for each. The entry is used by the Add and Create Problem Log Entry APIs.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key


8 8 BINARY(4) File number

12 C CHAR(10) Job name

22 16 CHAR(10) User

32 20 CHAR(6) Job Number

38 26 CHAR(10) File Name


Key 4002—File Data

This key contains the name of a data base file that is associated with the problem log entry.

This key is used to add or create an entry. It is also used to return the results of a retrieve operation.

To add or create an entry, use key 4002 (file data) to define each spooled file to be associated with the

problem. New entries are added to the file.

To change an entry it must be deleted first then a new ones added.

A retrieve is done by passing key 4000 and defining type 2. All data base file entries are returned, a key

4002 (file data) for each.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key


8 8 CHAR(10) File name

18 12 CHAR(10) File library name

28 1C CHAR(10) File member name


Key Group 5000—Contact Entries

This key group provides information about the contact.


v “Key 5000—Contact Entries”

v “Key 5001—Contact Information” on page 190

Key 5000—Contact Entries

Allows the retrieval of contact information, local, remote, or both. A key 5001 (Contact information) entry

is returned for each of the contact entries. This can be used by the Retrieve Problem Log Entry API.



Offset

Type Field Dec Hex

0 0 BINARY(4) Key


8 8 BINARY(4) Contact type

12 C BINARY(4) Contact information count


Key 5001—Contact Information

Allows creating or changing a contact entry. To create or change an entry:

v Provide the type of entry to create or change

v Set the key control to define the field to process.

The control values are:

1 NLV

2 Corporation name

4 Contact name

8 Primary contact phone number

16 Help desk or pager number

32 Address

64 CCSID

128 Primary FAX contact phone number

256 Alternative FAX contact phone number

512 Primary electronic mail address

1024 Alternative electronic mail address

To process multiple fields sum the value of the fields to be processed.

v Provide the data to be added to the field. Enter a blank to delete the contents of a field.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key



12 C BINARY(4) Contact type


20 14 CHAR(4) National language version

24 18 CHAR(36) Corporation name

60 3C CHAR(36) Name of contact

96 60 CHAR(30) Primary phone number

126 7E CHAR(30) Help desk or pager number

156 9C CHAR(30) Primary FAX number

186 BA CHAR(30) Alternative FAX number

Note: The following fields Address line 1 through Postal code pertain to the postal address.

216 D8 CHAR(36) Address line 1

252 FC CHAR(36) Address line 2

288 120 CHAR(36) Address line 3

324 144 CHAR(36) City or locality

360 168 CHAR(20) Country or region

380 17C CHAR(12) Postal code

392 188 CHAR(36) State or province

428 1AC CHAR(256) Primary electronic mail address

684 2AC CHAR(256) Alternative electronic mail address

940 3AC BINARY(4) Call central site support


Offset

Type Field Dec Hex

944 3B0 CHAR(8) Customer identifier 1




976 3D0 CHAR(8) Customer identifier 5

984 3D8 CHAR(7) Contract identifier 1

991 3DF CHAR(7) Contract identifier 2

998 3E6 CHAR(7) Contract identifier 3

1005 3ED CHAR(7) Contract identifier 4

1012 3F4 CHAR(7) Contract identifier 5

1019 3FB CHAR(1) Reserved

1020 3FC CHAR(256) Customer description 1





2300 8FC CHAR(256) Contract description 1

2556 9FC CHAR(256) Contract description 2

2812 AFC CHAR(256) Contract description 3

3068 BFC CHAR(256) Contract description 4

3324 CFC CHAR(256) Contract description 5

Key Group 6000—Problem History Entries

This key group provides problem history structures.

This section includes the following keys:

v “Key 6000—History Information”

v “Key 6001—History Information” on page 192

Key 6000—History Information

This key retrieves all or the last history entry. Key 6001 (history information) is returned for each history

entry. Entries are returned starting with the latest entry.



Offset

Type Field Dec Hex

0 0 BINARY(4) Key


8 8 BINARY(4) History type


Offset

Type Field Dec Hex

12 C BINARY(4) History count

Key 6001—History Information

History entries should be added to the file in logical event sequence and must be added each time the

problem log entry is created, changed, or elements are deleted. The create and add APIs add the entries

in the sequence the key 6001 (history information) are supplied to the API. No verification is made of the

logical order of the events. All entries that are added in the context of one API call have the same date

and time. The API adds the date and time.

Once entered the event may not be changed or deleted. Change control is provided to allow optional

data, change request name, and change request number to be added when needed.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key



12 C BINARY(4) History type

16 10 CHAR(13) Event date and time

29 1D CHAR(10) User ID

39 27 CHAR(10) Change request name

49 31 CHAR(6) Change request number


Key Group 7000—PTF Entries

This key group provides program temporary fix (PTF) information.


v “Key 7000—PTF Entry”

v “Key 7001—PTF ID” on page 193

v “Key 7002—PTF ID” on page 194

Key 7000—PTF Entry

Allows a user to retrieve or delete all PTF entries.

On a retrieve operation it defines the number of entries returned on a retrieve operation.

On a delete operation, all the PTF entries are deleted. Number of entries has no significance during

delete.




Offset

Type Field Dec Hex

0 0 BINARY(4) Key


8 8 BINARY(4) PTF count

Key 7001—PTF ID

This key defines the program temporary fix (PTF) identifier. On add or create operations, all fields must

be filled in.

On a retrieve operation, this key defines which PTF to retrieve. A PTF is identified by the PTF ID,

product, version, release, and modification.

PTF entries are always added to the end of the list.

To change a PTF entry, the key control should be used to identify the field being changed. The PTF ID

may not be changed.

Note: Ensure that the correct PTF entry is being changed. The SNDPTFORD command creates entries that

use special values for the product data. Non-IBM®

products may use the same PTF ID for different

releases or different vendors may use the same PTF ID. It may be necessary to retrieve, delete, and add

new PTF entries where there are multiple PTFs with the same PTF ID, but different product data, are

encountered. This exposure only exists with non-IBM PTFs since IBM PTFs have unique PTF identifiers.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key



12 C BINARY(4) PTF status

16 10 BINARY(4) Sent

20 14 BINARY(4) PTF ID length

24 18 CHAR(20) PTF ID

Note: The following fields Product ID length through Reserved pertain to the product data.










92 5C CHAR(2) Minimum level

94 5E CHAR(2) Maximum level


Offset

Type Field Dec Hex

96 60 CHAR(1) PTF image

Key 7002—PTF ID

On a create operation, all fields must be provided.

On a change operation, only the fields identified by the Key control field are processed.

On a retrieve operation, the PTF ordering options are returned.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key



12 C BINARY(4) PTF order type

16 10 BINARY(4) Option

20 14 BINARY(4) Reorder

24 18 BINARY(4) Delivery

28 1C BINARY(4) Check

32 20 BINARY(4) Delivery Format

36 24 CHAR(64) Image directory

100 64 CHAR(10) Image prefix

110 6E CHAR(10) Image catalog

120 78 BINARY(4) Image option

124 7C BINARY(4) PTF order status

Key Group 8000—Analyzed Error Entries

This key group provides analyzed error flag information.

Key 8000-Analyzed Error Flag: This key retrieves a value that indicates whether SLIC analyzed the

problem.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key


8 8 BINARY(4) Analyzed error flag


Key Group 9000—Logical Partition ID Entries

This key group provides logical partition ID information.

Key 9000-Logical Partition ID: This key retrieves the current logical partition ID on the physical machine.

Offset

Type Field Dec Hex

0 0 BINARY(4) Key


8 8 CHAR(1) Logical partition ID

Field Descriptions for Key Groups for Problem Log APIs

Address. Internet address of the client in dotted form. For example: 95.5.123.11.

Address line 1. The first line of the address.

Address line 2. The second line of the address.

Address line 3. The third line of the address.

Address type. The format of the unit address, which is numeric value that represents the hardware type.

Valid values are as follows:

1 Communications resource

2 Storage resource

3 Workstation resource

4 Auxiliary processor resource

5 Library resource

Alert status. Valid values are:

0 Problem not alertable

1 No alert pending

2 Alert pending

Alternative electronic mail address. The electronic mail (e-mail) address to receive problem-related data,

if the primary e-mail address is not available.

Alternative FAX number. The backup FAX number to receive problem-related data.

Analyzed error flag. Indicates whether the error has been analyzed by SLIC.

Answer code assigned. The code that is assigned corresponds to a message that describes the answer

given to the problem. The values are:

-1 No code assigned

0 Fixes sent

1 Fixes mailed

2 Fixes to be sent later

3 Fix cover letter only


4 Fixes not available

5 Fixes already on system

6 Not ordered

7 Fixes ordered or on system

8 All fixes on order

9 Exceeds mailing limit

10 Exceeds transmit limit

11 Exceeds limit for cover letter order

12 Support center notified

13 Documentation error

14 Failing product not entitled

15 Service requester not entitled

16 Reporting system not entitled

17 Entries out of order

Answer code returned. The code that is assigned corresponds to a message that describes the answer

given the service requester regarding the problem. See the answer code assigned field for list of values.

APAR library. The name of the library containing the saved APAR data for this problem. The library, if

present, contains spooled and database files. This data is collected automatically or by the Restore APAR

Data (RSTAPARDTA) or Save APAR Data (SAVAPARDTA) commands. The library is deleted when the

problem log entry is deleted.

Auto PAR. Defines if problem analysis procedures were automatically run for this problem.

0 Problem analysis not done automatically.

1 Problem analysis done automatically.

Auto notify. Defines if the problem has been automatically reported to a service provider.

0 Notify not done automatically.

1 Notify done automatically.

Board number. The number of the back plane card on this bus.

Bus number. The number of the bus.

Call central site support. It will be used to indicate that a customer want their Central Site Support


1 =

*YES

The central site support desk will be called by the CE or the Product Support center.

0 =

*NO

As a default , the central site support desk is not called.

Card location. The physical location of the card.

Card number. The number derived from the slot number (the logical address is assigned to the card slot).

Card position. Physical location where the device or feature is plugged into the bus.

Change request name. The name assigned, by the user, when submitting a change request.


Change request number. The sequence number of the change request.

Check. Indicates whether checking is performed on the service requester system to determine if PTFs are

ordered based on whether or not the PTF product is installed or supported. Possible values are:

*NO The PTFs specified on the PTF order list are ordered even when the PTF product is not installed or supported

on the service requester.

*YES The PTFs specified on the PTF order list parameter are ordered only if the PTF product is installed or

supported on the service requester.

Note: *NO must be specified when 1 (Cover letter only) is specified for PTF order type.

City or locality. The city or locality of the postal address.

Class of FRU. The class of FRU entries to process. The values are:

0 All FRU classes

1 Point of failure

2 Partial isolation

3 Isolation

4 Verification

5 Recovery

6 Answer

All FRUs can only be used on a retrieve operation.

Client ID. Name of the client.

Client ID length. Length of the client ID data.

Code. A code that defines the network address type.

A APPN

I Internet

R *IBMSRV

Coded character set identifier (CCSID). A code that describes the character set of the text. This value

should be changed each time data is written and the value must agree with the CCSID of the data. If this

value is 0 on a create operation, the API uses the job CCSID.

Contract identifier 1, 2, 3, 4 and 5. The contract identifer. The following special values might be

returned:

*NONE No additional contract identifer information is provided.

Contract description 1, 2, 3, 4 and 5. The contract description is returned as UTF8. The following special


*NONE No additional contract description information is provided.

Contact information. Data describing the PC contact.

Contact information count. The number of 5001 keys that are returned by the retrieve operation.


Contact information length. Length of the contact information data. If it is a local contact information

record, it is the local corporation name, or else it is the remote system corporation name.

Contact type. Origin of contact information, local or remote. The values are:

1 Contact information of the local system

2 Contact information of the system on which the problem was created.

Corporation name. Name of company that depends on the entry type.

Count. Number of times the problem has been detected.

Country or region. The country or region of the postal address.

Create date and time. Time the problem log entry was created and added by the API. It is in format

CYYMMDDHHMMSS. Ignored if the create was local.

Create location. Defines where problem was created. The values are:

1 Local

2 Remote

Creator of entry. Defines the function that created the entry.

-1 Not defined

0 Alert

1 FFDC, first failure data capture

2 FAST

3 General

4 PWSI

Customer identifier 1, 2, 3, 4 and 5. The customer identifier. The following special values might be

returned:

*NONE No additional customer id information is provided.

Customer description 1, 2, 3, 4 and 5. The customer description is returned as UTF8. The following

special values might be returned:

*NONE No additional customer description information is provided.

Date and time added. Date and time the problem log entry was added. This is the time that the problem

was added to this systems problem log. This field is only valid for the QsxRetrieveProblemLogEntry API.

This is entered by the create API when the problem is added to this system. The time added field cannot

be changed once entered, but it can be retrieved.

Date and time closed. Date and time the problem log entry was closed.

This field is changed when the user selects close on the Work with Problem display or uses the Change

Problem Log API. This field can be retrieved, but it cannot be changed.

Delivery. Defines whether the PTF will be delivered by mail or electronically.


0 Deliver by mail or electronically.

1 Deliver electronically only.

Delivery format. Specifies the format the PTFs are stored. Possible values are:

0 PTFs are delivered electronically as save files.

1 PTFs are delivered electronically as optical image files. The optical image files will contain PTFs

and cover letters. The optical image files will be stored in the directory specified in the image

directory field.

Delta level. Specifies the level of the system release.

Dependent address 2. An address field where the type of address is dependent on the address type field.

Address Type Dependent Address 2

1 (Communications) Adapter

2 (Storage) Controller

3 (Workstation) Adapter

4 (Auxiliary processor) Auxiliary processor

5 (Library) Library



1 (Communications) Port

2 (Storage) Device

3 (Workstation) Port

4 (Auxiliary processor) Adapter

5 (Library) Controller



1 (Communications) Channel

2 (Storage) Reserved

3 (Workstation) Device

4 (Auxiliary processor) Port

5 (Library) Device



1 (Communications) Reserved

2 (Storage) Reserved

3 (Workstation) Shared session

4 (Auxiliary processor) Reserved

5 (Library) Reserved

Device location. The physical location of the device.

Device location text. Text that describes the location of the device.


Device location text length. Length of text.

Device name. A name given to the device or feature.

Device type. The type of device located on the system.

Document reference message ID. Message that contains a description of reference material.

DSA bus number. Code further defining the electrical address of a resource.

EC number. Engineering change number.

Error code message identifier. Identifier of the message that describes the error log entry.

Error log identifier. Number of the error log.

Event date and time. Date and time event was added to the problem log entry.

Exit point of the PDP. A code that defines the procedure in the PDP that isolated the problem.

Fault symptom code. A code defining the symptom of the problem.

Feature. Feature of the device. This is set to blank if a feature is not applicable.

Feature length. Length of the feature field. Maximum length supported is 4.

File count. The number of series 4001 or 4002 keys that are concatenated to this key.

File library name. Name of the library that contains the file.

File member name. Name of the file member. This is *SAVF if the file is a save file. This is *NONE if the

file has no members.

File name. The file name that was specified by the user program when the file was created, or the name

of the device file used to create this file.

File number. The file number for this spooled file.

File type. The type of entry to process. The values are:

0 All entries

1 Spooled file entry

2 Data file entry

Filter event Defines if problem log should be filtered

0 Not set

1 No alert pending

2 Alert pending

Filter group assigned. Name of the group in the filter to which the problem is assigned.

Filter library name. Library where the filter is located.

Filter name. Name of the filter.


Frame ID location. The physical location of the frame ID.

FRU code. A code that defines the FRU.

FRU count. Number of FRU entries that were returned by the Retrieve Problem Log API.

FRU description message ID. Message that describes this FRU.

Function. Name of the failing function.

Function length. Length of the function data.

Help desk or pager number. The help desk or pager number of the contact for the problem being

reported. This number should include the area code, exchange numbers, and the extension.

Hierarchy. The function of the program where the problem occurred.

History count. The number of 6001 keys returned by the Retrieve Problem Log API.

History type. History entry type. The types are:

0 Problem entry closed

1 Problem entry opened

2 Service request received

3 Opened by an alert

4 Problem analyzed

5 Verification test ran

6 Recovery procedure ran

7 Prepared to report

8 Service request sent

9 Problem answered

10 Response sent

11 Reported by voice

12 Fixes transmitted

13 Change request submitted

14 Change request ended

15 Fix verified

16 Remote analysis

17 Remote verification ran

18 Remote recovery ran

19 Alert created

20 APAR created

21 APAR data collected

22 APAR data restored

23 APAR data deleted

24 Changed by CHGPRB

25 Deleted by DLTPRB

26 Problem occurred multiple times

27 Status changed

28 Status query sent

29 Problem automatically analyzed

30 Problem not automatically analyzed - SRC

31 Problem not automatically analyzed - SBMJOB

32 Automatic problem analysis failed

33 Problem sent automatically

34 Problem not sent automatically - SRC off


35 Problem not sent automatically - SBMJOB

36 Automatic problem notification failed

37 Problem analysis failed

Image catalog. Indicate name of the image catalog to create. The following special value is accepted:

*NONE This option disables the image catalog creation.

Image directory. The path name of the directory where optical image files will be saved. For more

information about specifying path names, see Object naming rules in the Control language topic

collection. The following special value is accepted:

*DFT The optical image files are stored in /QIBM/UserData/OS/Service/ECS directory.

Image option. Specify if the image order will be submitting the order or submitting the order and

download the image. The following values are accepted:

0 Submit order and download.

1 Submit the order.

Image prefix. The prefix for the optical image file names. If multiple images are received under one

order, the files will be uniquely identified by a numerical suffix on the image name. This field must be set

to blanks if 1 (Image) is not specified for delivery format. The following special value is accepted:

*SRVPVD No prefix will be added at the beginning of each optical image file name. The files will be named

by the service provider.

Instruction. Instruction number where the error was detected.

I/O bus address. The bus number between the IOP and the device.

Isolation status. The status of the isolation attempt.

0 Not isolated, no FRUs added.

1 Completed successfully with isolation FRUs added.

2 Completed successfully, no problem found, point of failure FRUs added.

3 Unsuccessful, point of failure FRUs added.

4 Analysis not complete, point of failure FRUs added.

5 Analysis partially completed, partial FRU list added.

Job name. The name of the job that produced the spooled file.

Job number. The number of the job that produced this spooled file.

Key. Integer value that defines the key you are working with.

Key control for key 6. Defines the fields that will be processed.

1 Alert status


2 APAR library

4 Auto PAR

8 Auto Notify

16 From System

32 To System

64 Prepared For

Key control for key 8. Defines which field should be processed. Add the values to process multiple

fields.

1 Use answer code assigned

2 Use answer code returned

4 Use problem number

8 Use problem country number

16 Use problem branch number

32 Use PTF order ID

64 Use first URI

128 Use second URI

Key control for key 1004. Defines the EC (engineering change) number.

Key control for key 1005. Defines the fields that will be processed.

1 Type

2 Device

4 Product

8 Instruction

16 Hierarchy

32 Resource name

64 Error log identifier

128 Program

Key control for key 1006. Defines field used for reporting code:

1 Product name

2 Program name

4 Probe

Key control for key 1014. Defines which field should be processed. Add the values to process multiple

fields.

1 Use count field

2 Use object length, object name and detecting product fields

Key control for key 5001. Defines contact data fields:

1 National Language Version (NLV)

2 Corporate name

4 Contact

8 Primary phone number

16 Help desk or pager number

32 Address


64 CCSID

128 Primary FAX contact phone number

256 Alternative FAX contact phone number

512 Primary electronic mail address

1024 Alternative electronic mail address

2048 Call central support

4096 Customer id 1

8192 Customer id 2

16384 Customer id 3

32768 Customer id 4

65536 Customer id 5

131078 Contract id 1





4194304 Customer description 1





134217728 Contract description 1





Key control for key 6001. Defines which fields to process:

1 Use optional change request data

Key control for key 7001. Identifies which fields to process on a change operation. The control values are:

1 Status

2 Sent

To process multiple fields sum the values for the fields you want to change.

Key control for key 7002. Defines which fields to process on a change operation. The control values are:

1 Type

2 Option

4 Reorder

8 Delivery

16 Check

32 Delivery Format

64 Image directory

128 Image prefix

254 Image catalog

512 Image option

1024 PTF order status

Key size. Defines the size of the key you are working with.


Length of URI 1. The length of the URI 1. The maxium length is currently 1024.

Length of URI 2. The length of the URI 2 The maxium length is currently 1024.

Machine type. A type of device.

Machine type length. Length of the machine type in bytes.

Maximum level. The indicator of the highest level of the product on which this PTF can be installed. If

the minimum and maximum levels are the same, then this PTF can only be installed on one level of the

product. The level can be AA to 99. This field will be blank if the product has no level.

Media type. This is a code that defines a media type.

1 Automatic selection. Auto selection implies that the system determines what device to use for fix distribution.

This is required when the problem is PREPARED.

If the system does not detect any device, the default

value will be *DVDROM.

2 CD-ROM.

3 DVD-ROM.

Message file name. The message file that contains the problem description. The library of the file must

exist in the library list.

Message identifier. The identifier of a message that describes the problem.

Message library name. The library that contains the message file.

Minimum level. The indicator of the lowest level of the product on which this PTF can be installed. If

the minimum and maximum levels are the same, then this PTF can only be installed on one level of the

product. The level can be AA to 99. This field will be blank if the product has no level.

Model. The model of the device type.

Model length. Size of the machine model field, maximum is 3.

Mode of analysis. Whether the problem was in message mode, which allows the user to analyze the

problem, or the problem was analyzed by the System Licensed Internal Code (SLIC) and cannot be

analyzed again. Valid values are as follows:

0 Message mode of analysis

1 SLIC mode of analysis

Modification level. Modification level of the object. *ONLY is a valid constant even though it is longer

than the 2-byte maximum.

Modification level length. Length of the modification level in bytes. Maximum length supported is 2.

Module name. Component of a program or a program name.

Name. Product, microcode, application, or module name.

Name length. Length of the name of the object that detected the error.

Name of contact. The name of a person to contact within the corporation.


National language version. A code that defines the national language version in which the cover letter is

supplied. The values are defined in the i5/OS®

globalization topic collection.

Network address. Defines the address of a network node. These formats are used:

APPN v Network ID

v Control point name

v Reserved

Internet (in dotted form) v Address

v Reserved

*IBMSRV v Network ID (must be blank)

v Control point name (must be ’*IBMSRV’)

v Reserved

The reserved fields must be blank.

Number of times analyzed. The number of times the problem was analyzed. The value must be greater

than 0 and should be incremented each time the problem is analyzed.

Object name. Name of the object that detected the error.

Offset to URI 1. The offset of the URI 1

Offset to URI 2. The offset of the URI 2.

Option. Defines if only the PTFs listed will be ordered or the PTFs and its requisites.

0 PTF with no requisites

1 PTF and requisites

Part location. A textual description of where the part is located.

Part number array. List of up to six part numbers, 12 characters in length. Unused elements of the array

should be blank.

Path name. Path to the failing software.

Path name length. Length of the path name data.

PDP. Name of the problem determination procedure (PDP) module used to isolate the error.

Pointer to the text. Address of the text.

Port. Code defining where a device is attached to a device driver.

Postal code. The postal or zip code of the postal address.

Primary electronic mail address. The electronic mail (e-mail) address to receive problem-related data.

Primary FAX number. The primary FAX number to receive problem-related data.

Primary function group. The load ID of the program.


Primary phone number. The phone number of the primary contact for the problem being reported.

Probability of fix. The probability of this FRU resolving the problem.

Probe. Identifier for a problem found in a program.

Problem branch number. A number assigned by the support system. The problem branch number field is

typically the problem management branch number used by *IBMSRV.

Problem category. Defines how a problem should be processed.

0 REPORT-Designates a set of problem log entries that can be reported. This includes all problems except for

LOGONLY problems.

1 CRITICAL-Designates a set of problem log entries that have been created from a critical message. These

problems should be handled immediately.

2 LOGONLY-Designates a set of problems that are log-only. These problems cannot be reported.

3 ALL-All program log entries are displayed

Problem country number. A number assigned by the support system. The problem country number field

is typically the problem management country number used by *IBMSRV.

Problem log identifier. A unique identifier based on date and time, network type and network address.

The values are:

Number On a create operation, this key defines whether the problem is being created for a local or remote

problem. A constant of ″*LOCAL″ is used to identify the problem as a local one.

The problem log ID is provided in key 1 (Problem log ID) when a remote problem is being

created.

Network type Network type

A APPN address

Network address Identifies the network in which the system resides. The format is:

v 8 characters for the network ID

v 8 characters for the control point name

v 4 characters reserved (must be blank)

Problem number. A number assigned by the support system. The problem number field is typically the

problem management number used by *IBMSRV.

Problem severity. The impact of the problem on the system. The values are:

1 High

2 Medium

3 Low

4 None

Problem status. Defines the current status of the problem. The values are:

0 *OPENED status

1 *READY status

2 *SENT status

3 *ANSWERED status

4 *VERIFIED status

5 *PREPARED status


6 *CLOSED status

Problem type. Defines the type of problem the system is processing. The values are:

1 Machine-detected problem

2 User-perceived hardware or software problem

3 PTF orders

4 User-perceived remote problem

5 Application-detected problem

6 Client machine-detected problem

7 Client user-detected problem

8 User-created general problem

Product ID. Name of the product.

Product ID length. Length of the product ID data. The maximum length is 7 except for key 1013 where

the maximum is 64. *ONLY*PRODUCT** is a valid constant even though it is longer than the 7-byte

maximum.

Program. Name of the failing program.

Program length. Length of the program data.

PTF count. Number of PTF entries retrieved.

PTF ID. A program fix identifier.

PTF ID length. Length of the program fix identifier. Maximum length is 7.

PTF image. Identifies whether or not the PTF was downloaded as an optical image file on the system.

Possible values are:

0 The PTF was not downloaded as an optical image file.

1 The PTF was downloaded on the system as an optical image file.

PTF Order ID. Specifies a unique number for PTF orders.

PTF order status. Indicates the status of the PTF order image. Possible values are:

0 None

1 On-order

2 Downloaded

3 Canceled

4 Scheduled

5 Failed

6 Mailed

PTF order type. Defines if the PTF and its cover letter will be ordered or only the cover letter.

0 PTF and cover letter

1 Cover letter only


PTF status. Identifies whether the PTF has been requested from a remote system. Requested implies that

the PTF order was sent and the PTF is needed by your system.

0 PTF not requested

1 PTF requested

Query status. Defines how the client service information is to be processed.

0 Field not defined

1 Service representative opened the problem

2 Service representative has been dispatched

3 Problem closed

4 Problem closed and service representative has been dispatched

Rack serial number. Serial number of the rack.

Rack serial number length. Length of the serial number of the rack.

Recovery status. The status of the recovery attempt.

0 Recovery status not available

1 Recovery status available

2 Fix verified

3 Recovery failed

Reference code. Index into a reference code translatable table.

Reference code description data. Data defining the error.

Reference code description file name. File that contains the reference code description.

Reference code description library name. Library that contains the reference code description.

Reference code description message. Message identifier that describes the problem.

Reference code translate table identifier. Name of the table that contains a description of the problem.

Reference code translate table library. Library that contains the reference code translate table.

Release level. Release level of the object. *ONLY is a valid constant even though it is longer than the

2-byte maximum.

Release level length. Maximum length supported is 2.

Reorder. Defines if a PTF that is already on the system, but which does not have a save file, will be

reordered. Typically a PTF will not be ordered if it has been loaded or installed. This option overrides

normal operation but if a save file exists for the PTF it will not be reordered.

0 Do not reorder a PTF that is available on the system.

1 Order a PTF for which there is no save file for that PTF exists on the system.

Replacement text. Defining the configuration error.

Replacement text length. Length of the data in bytes.


Reserved. Space added to ensure correct boundary alignment. This field must be blank.

Resource name. Name of the resource.

Screen identifier. The identifier of a screen to be displayed to assist in solving a problem.

Secondary function group. Program option.

Sense bytes. Sense bytes that pertain to the problem.

Sent. Defines if the PTF has been sent from the remote system in response to a PTF order or problem

report.

0 PTF not sent

1 PTF sent

Serial number. Manufacturing sequence number or designation.

Serial number length. Maximum length supported is 12, except for the maximum length of the machine

serial number (key 5) that is 7.

State or province. The state or province of the postal address.

Symptom. An encoded string that represents the problem description. Typically, this field contains

EBCDIC uppercase alphabetic, numeric, and limited special characters. Contact your service

representative for data restrictions. This field is considered a user-defined field and no translation or

alteration of the contents are made. The first character position of the field cannot be blank.

Text count. A count of 3001 entries returned by the Retrieve Problem Log API of entries returned. If no

entries are found, 0 is returned.

Text length. Length of the data in bytes.

Text type. A code that defines the type of text to process. The values are:

0 All text, used on key 3000 (text entry) only to retrieve all entries.

1 80-character title, limit to one entry

2 Long problem description

3 Problem status

4 Private notes

5 Associated problem data

Transport type. The type of connection from the central electronics complex (CEC) to the board’s

user-assigned value for this SPD bus.

Type of hardware. Machine, device, feature, or component type.

Unit address. Code defining the electrical address of a resource.

URI Information 1. The information of the URI (Universal Resource Identifier) 1. The URI is the value

the service provider uses to identify the problem reported.

URI Information 2. The information of the URI (Universal Resource Identifier) 1. The URI is the value

the service provider uses to identify the problem reported.


User assigned. The user profile of the person assigned to this problem. The value is blank if not assigned.

User ID. User ID of the job making the entry.

Verification status. Defines the status of the recovery attempt.

0 Not available

1 Available

2 Fixed

3 Failed

Version. Release level of the product. *ONLY is a valid constant even though it is longer than the 2-byte

maximum.

Version length. Length of the version data. Maximum length supported is 2 except for key 1013 where

the maximum is 64.

Volume ID. Identifier of the media that is failing.


QTRC Trace Definitions

The following definitions are common to the QTRC Trace APIs:

A

Active Trace Level

The Trace Level that is currently active for a given application Component. The active trace level is

specified when a Trace Collection is started, using the Start Trace (STRTRC) CL command. The user

indicates which component and at what trace level they want that component to trace. The terms

used to describe the active trace level for a given component include: ERROR Trace, INFO Trace,

and VERBOSE Trace. Since the active trace level is specific to a component, different components

can have different active trace levels. The “QtrcGetActiveLevel()—Get Active Trace Level” on

page 73 function will indicate an active trace level of NONE if a trace collection is not active, or if

the component is not part of an active trace collection.

C

Coded Trace Level

The Trace Level that is specified in the application code, for each Trace Point. The application

developer chooses the appropriate trace level based on the type of data to be collected. This could

also be called the desired trace level, since it becomes the indicator, based on the Trace Conditions,

as to whether a trace point will actually be written as a Trace Record. The coded trace level is also

shown in the trace output for each trace record that is written. The terms used to describe a

coded trace level, as seen in the application code, include: ERROR-level Trace Point, INFO-level

Trace Point, and VERBOSE-level Trace Point.

Component

A 10-byte character string which names the application component. Each Trace Point has an

associated component that is specified on the QTRC Trace APIs. The component name is also

shown in the trace output for each Trace Record that is written. A component is defined to the

QTRC Trace environment when specified on the Start Trace (STRTRC) CL command. Component

names should only contain characters in the invariant character set. Avoid using lowercase a

through z. Application component names should contain an abbreviated company name along


#TOP_OF_PAGE

aplist.htm

with the application name. Component names starting with an asterisk (*) are reserved for the

operating system. Component names starting with Q are reserved for IBM®

licensed programs.

E

ERROR-level Trace Point

A Trace Point which has a Coded Trace Level of ERROR. The trace data will be written as a Trace

Record when the Trace Conditions are met and the component’s Active Trace Level is set to either

ERROR, INFO, or VERBOSE. For more information, see “QTRC Trace Levels” on page 214.

ERROR Trace

A Trace Collection that is started, using the Start Trace (STRTRC) CL command, where the trace

data collected for a given Component should only include error conditions. It indicates the type

and amount of trace data that will be collected. For more information, see “QTRC Trace Levels”

on page 214. An ERROR Trace means the Active Trace Level for a given component is set to

ERROR, hence only ERROR-level Trace Points will be written as a Trace Record to the trace

collection, if the Trace Conditions are met.

F

Function

An optional character string, up to 512 bytes, which can be specified on a Trace Point. The

function can be used to identify a function, program, procedure, class, or method name, among

other things, and is shown in the trace output for each Trace Record that is written. If no function

is defined, *NONE will be shown. Function should only contain characters in the invariant

character set. For example, the function could be ″MYLIB/MYPGM,″ ″MyFunction(),″ or

″MyClass::MyMethod(int,void *).″

I

INFO-level Trace Point

A Trace Point which has a Coded Trace Level of INFO. The trace data will be written as a Trace

Record when the Trace Conditions are met and the component’s Active Trace Level is set to either

INFO or VERBOSE. For more information, see “QTRC Trace Levels” on page 214.

INFO Trace


data collected for a given Component should include informational data and error conditions. It

indicates the type and amount of trace data that will be collected. For more information, see

“QTRC Trace Levels” on page 214. An INFO Trace means the Active Trace Level for a given

component is set to INFO, hence both INFO-level Trace Points and ERROR-level Trace Points will be

written as Trace Records to the trace collection if the Trace Conditions are met.

L

Label An optional character string, up to 128 bytes, which can be specified on certain Trace Points. The

label can be used to identify or describe the trace data. The label should only contain characters

in the invariant character set. For example, if a structure named myStruct is being written by the

“QtrcWriteHexDumpF()—Write Hexadecimal Dump Formatted Trace Data” on page 79 function,

the label could be something like ″Contents of myStruct after initialization.″


S

Subcomponent

An optional 10-byte character string which can be specified on a Trace Point. The subcomponent

further classifies the trace data, and is shown in the trace output for each Trace Record that is

written. If no subcomponent is defined, *NONE will be shown. The subcomponent can be used to

identify related sections within a Component. Each trace point can have a subcomponent

associated with it. Subcomponent should only contain characters in the invariant character set.

Avoid using lowercase a through z. For example, the component could be XYZ_LOANS and the

subcomponents could be HOME, AUTO, and RV.

T

Trace Collection

A trace that has been started and is now collecting trace data to a common storage area. This is

accomplished through the Start Trace (STRTRC) CL command, which also uses the term trace

session to describe this process.

Trace Conditions

The conditions that must be met in order for a Trace Point to be written out as a Trace Record. The

conditions include: 1) A Trace Collection must be started and active for the current thread, 2) The

Component is part of the trace collection (namely, an Active Trace Level is set for that component),

3) The trace point must have a Coded Trace Level that allows trace data to be written based on the

active trace level.

Trace Level

There are 3 trace levels: ERROR, INFO, and VERBOSE. Trace levels are used to describe both an

Active Trace Level as well as a Coded Trace Level. For more information, see “QTRC Trace Levels”

on page 214.

Trace Point

The location within a program where an application developer has coded a call to a QTRC Trace

API to write trace data. Trace data can include a string of text, a hexadecimal dump, or a call

stack.

Trace Record

A Trace Point that was actually written out, and is now part of a Trace Collection.

V

VERBOSE-level Trace Point

A Trace Point which has a Coded Trace Level of VERBOSE. The trace data will be written as a Trace

Record when the Trace Conditions are met and the component’s Active Trace Level is set to

VERBOSE. For more information, see “QTRC Trace Levels” on page 214.

VERBOSE Trace


data collected for a given Component should include detailed data, informational data, as well as

error conditions. It indicates the type and amount of trace data that will be collected. For more

information, see “QTRC Trace Levels” on page 214. A VERBOSE Trace means the Active Trace

Level for a given component is set to VERBOSE, hence all VERBOSE-level Trace Points, INFO-level

Trace Points, and ERROR-level Trace Points will be written as Trace Records to the trace collection if

the Trace Conditions are met.

Top | “QTRC Trace APIs” on page 72 | APIs by category


#TOP_OF_PAGE

aplist.htm

QTRC Trace Levels

There are 3 trace levels that can be selected: ERROR, INFO, and VERBOSE. The trace levels are inclusive.

An active trace level of NONE indicates trace is not active for a given component. The following table

demonstrates which component’s trace points are collected based on the active trace level, so long as the

other trace conditions are met.

Active Trace Level Error-level trace point Info-level trace point Verbose-level trace point

NONE No No No

ERROR Yes No No

INFO Yes Yes No

VERBOSE Yes Yes Yes

Choosing the Coded Trace Level

Each component decides how to use the coded trace level on each trace point to define the level of detail

that is collected when a particular active trace level is specified for that component. During application

development, it is fairly common to change the coded trace level, after reviewing trace records collected

for a particular active trace level. The following recommendations generalize how a coded trace level

should be selected when enabling a component for trace:

v ERROR-level trace point: Use this type of trace point when returning from a program or function with

an error condition, encountering an unexpected return code or exception condition, or upon receiving

invalid input. These types of trace points should help determine why a given error condition or other

failure condition is being reported by the application. The goal is to not have any ERROR-level trace

points collected under normal running conditions, so that tracing a failure condition using an ERROR

trace will be distinct. ERROR-level trace points are also collected for an INFO trace as well as for a

VERBOSE trace.

v INFO-level trace point: Use this type of trace point to provide informational data such as to indicate

entry and exit from a program or major function, to show parameter values and return codes, or to

show major flow changes due to input or other environment conditions. These types of trace points

should help determine why certain processing was performed or why a given action was taken.

INFO-level trace points are also collected for a VERBOSE trace.

v VERBOSE-level trace point: Use this type of trace point to include detailed data, control flows, data

structures, environment conditions, internal state conditions, call stacks, resource allocations, or the use

of synchronization methods. These types of trace points should provide additional detailed data that

would otherwise not be collected in an ERROR trace or INFO trace due to their large size or

insignificance. Any useful data that may aid in debug should be collected. VERBOSE-level trace points

are only collected for a VERBOSE trace.


QTRC Trace Data Collected

Trace Data Collected

Each trace point specifies various items of information. When a trace point is written to a trace collection

because the trace conditions are met, the items become part of the trace record. The specified items

include the following:

v Coded trace level

v Component

v Subcomponent (optional)


#TOP_OF_PAGE

aplist.htm

v Function (optional)

v Trace data type (string of text, hexadecimal dump, or call stack)

v Trace data

Note: When writing trace data, applications must be cautious about writing sensitive or confidential

information. If an application works with passwords or encryption keys, the application must never write

the clear text or encrypted values of the password or key as part of the trace data. The application should

instead use blanks or a special value such as *PASSWORD.

Trace Data Automatically Collected

In addition to the specified items, there is additional information that automatically gets collected when a

trace record is written to the trace collection. The additional information that automatically gets collected

include the following:

v Job

v Timestamp

v Thread ID

v Current User Profile

v Process ID (PID)

v Remote IP Address

v Port Number

Print Trace (PRTTRC) Output

The following items are either defined as a column heading or an individually labeled item in the Print

Trace (PRTTRC) CL command output. When a QTRC Trace API is used to write component trace data,

the following items are associated with the trace record:

v JOB - Name of the job.

v TIME - Timestamp.

v THREAD - Thread ID.

v COMPDATA - Trace data specific to the component that created the trace record. This function (type of

trace entry) indicates the trace record was generated by calling a QTRC Trace API.

v COMPONENT - The 10-byte component name.

v TRACE LEVEL - The coded trace level. Indicates the type of trace point. Possible values are ERROR,

INFO, or VERBOSE.

v SUBCOMPONENT - The (optional) 10-byte subcomponent that was specified for the trace record. If

not specified on the trace point, *NONE is displayed.

v CURRENT USER PROFILE - The user profile that was in effect for the thread at the time the trace

record was written.

v PID - The process identifier of the job at the time the trace record was written.

v TRACE TYPE - The type of trace data. Possible values are TEXT, HEX, or STACK.

v REMOTE IP ADDRESS - The remote IP address of the thread at the time the trace record was written.

v REMOTE PORT - The remote port of the thread at the time the trace record was written.

Note: The (optional) function, if specified on the trace point, follows the labeled items. If not specified,

*NONE is shown.

Note: The actual component trace data (string of text, hexadecimal dump, or call stack) follows the

labeled items and (optional) function.

For additional information, see “QTRC Trace Collecting a Component Trace” on page 216.



QTRC Trace Collecting a Component Trace

The Start Trace (STRTRC), End Trace (ENDTRC), Print Trace (PRTTRC), and Delete Trace (DLTTRC) CL

commands are used for collecting and managing QTRC Trace component data. It is recommended that a

separate library be created, such as TRCDATA, that will only be used for storing trace data. This library

can be used during ENDTRC, such that collected trace data is stored into database files in that library.

Start Trace (STRTRC)

The Start Trace (STRTRC) CL command has a Trace type (JOBTRCTYPE) parameter. The Trace type

parameter must either be *ALL or contain the special value *TRCTYPE in order to specify a QTRC Trace

component. The Trace type: Component / Trace level (TRCTYPE) parameter is used to specify one or

more QTRC Trace components and their associated active trace level (*ERROR, *INFO, or *VERBOSE).

The following examples focus mainly on how to define QTRC Trace components and their associated

active trace levels for the indicated trace collection (session):

v The following CL command will start a trace collection (session) called TRC0000001 for the current job.

An ERROR trace for the component MYCOMP will be defined to the QTRC Trace environment.

STRTRC SSNID(TRC0000001) JOBTRCTYPE(*TRCTYPE) TRCTYPE((MYCOMP *ERROR))

v The following CL command will start a trace collection (session) called TRC0000002 for a target job

called 123456/APPUSER/APPJOB. An INFO trace for the component MYCOMP will be defined to the

QTRC Trace environment. The trace collection will also contain *FLOW and *DATA job trace type data.

STRTRC SSNID(TRC0000002) JOB((123456/APPUSER/APPJOB))

TRCTYPE((MYCOMP *INFO))

v The following CL command will start a trace collection (session) called TRC0000003 for any existing

job, or job that may not have even started yet, which matches the job name APPJOB and user

APPUSER. A VERBOSE trace for the component MYCOMP and an ERROR trace for the component

THATCOMP will be defined to the QTRC Trace environment. Note: When a generic job name is used,

it is very important to make sure the trace collection (session) is ended through the use of the End

Trace (ENDTRC) CL command when the trace is no longer needed, otherwise trace data will be

collected indefinitely.

STRTRC SSNID(TRC0000003) JOB((*ALL/APPUSER/APPJOB)) JOBTRCTYPE(*TRCTYPE)

TRCTYPE((MYCOMP *VERBOSE) (THATCOMP *ERROR))

End Trace (ENDTRC)

The End Trace (ENDTRC) CL command is used to end a trace collection (session) that was started by a

STRTRC CL command. The Data library (DTALIB) parameter can be used to indicate which library the

trace data should be stored in. It is recommended that a data library be used, such as TRCDATA. The

ENDTRC CL command also has the option to delete the collection, through the Data option (DTAOPT)

parameter. The special value *DLT can be used if the trace collection (session) is not needed. The

ENDTRC CL command can also be used to print the trace data, using the Print trace data (PRTTRC)

parameter. If the special value *YES is used, the trace data will be printed at the time the trace is ended.

The following examples show how to end trace collections (sessions), using the various options that were

discussed:

v The following CL command will end a trace collection (session) called TRC0000001, store trace data in

the TRCDATA library, and print the trace data.

ENDTRC SSNID(TRC0000001) DTALIB(TRCDATA) PRTTRC(*YES)

v The following CL command will end a trace collection (session) called TRC0000002, and delete the

trace data that was collected. This option is used when a trace was performed, but is later determined

the trace data is not needed.

ENDTRC SSNID(TRC0000002) DTAOPT(*DLT)


#TOP_OF_PAGE

aplist.htm

v The following CL command will end a trace collection (session) called TRC0000003 and store the trace

data in the TRCDATA library. The trace data can be later printed using the Print Trace (PRTTRC) CL

command.

ENDTRC SSNID(TRC0000003) DTALIB(TRCDATA)

Print Trace (PRTTRC)

The Print Trace (PRTTRC) CL command is used to print a trace collection (session) that was stored to a

data library when the ENDTRC CL command was used. The PRTTRC CL command also has the option

to delete the trace data through the Delete trace (DLTTRC) parameter. The following examples show how

to print trace collections, using the various options that were discussed:

v The following CL command will print a trace collection (session) called TRC0000001 from the trace

data library TRCDATA.

PRTTRC DTAMBR(TRC0000001) DTALIB(TRCDATA)

v The following CL command will print a trace collection (session) called TRC0000003 from the trace

data library TRCDATA. After the trace collection is printed, the trace data will be deleted.

PRTTRC DTAMBR(TRC0000003) DTALIB(TRCDATA) DLTTRC(*YES)

Delete Trace (DLTTRC)

The Delete Trace (DLTTRC) CL command is used to delete a trace collection (session) that was stored to a

data library when the ENDTRC CL command was used. The following example shows how to delete a

trace collection:

v The following CL command will delete a trace collection (session) called TRC0000001 from the trace

data library TRCDATA.

DLTTRC DTAMBR(TRC0000001) DTALIB(TRCDATA)

For additional information, see “QTRC Trace Data Collected” on page 214.


QTRC Trace Tips

Performance

When a QTRC Trace API is called, the trace conditions for the specified component are always checked.

When tracing is not active for the specified component, and the QTRC Trace APIs are called multiple

times, there may be a noticeable performance impact. To avoid the performance impact the

“QtrcGetActiveLevel()—Get Active Trace Level” on page 73 API can be used, and the results saved into a

variable for later uses. Assume an application program does the following:



QtrcGetActiveLevel(myComp, &myCompActLvl);

The application can use the myCompActLvl variable to quickly check if the component’s active trace level is

in effect, just prior to calling any of the QTRC Trace APIs that write trace data.

Condition to Check API Coded Trace Level

if (myCompActLvl >= QTRC_LEVEL_ERROR) QTRC_LEVEL_ERROR

if (myCompActLvl >= QTRC_LEVEL_INFO) QTRC_LEVEL_INFO

if (myCompActLvl >= QTRC_LEVEL_VERBOSE) QTRC_LEVEL_VERBOSE


#TOP_OF_PAGE

aplist.htm

It is important that the if-condition checks for greater than or equal to the trace level. This is done to

keep the same semantics of how the QTRC Trace APIs check the component’s active trace level against

the coded trace level parameter. The variable should be periodically updated, using the

QtrcGetActiveLevel() API, to ensure a current view of the component’s active trace level. For example,

the variable should be updated in the following conditions:

v Upon entry to a program or major function.

v After coming out of a wait.

v After calling a long-running program or function.

v After each iteration of a major loop cycle.

A simplified check of the variable could be used instead, for those cases where the performance impact is

less critical, when any type of tracing (ERROR, INFO, or VERBOSE trace) is active:

if (myCompActLvl != QTRC_LEVEL_NONE)

In some cases, the performance impact of tracing, whether tracing is active or not, is of no concern. This

is most often the case for ERROR-level trace points, since error conditions should not normally occur

within the application. Namely, the ERROR-level trace points would normally not be reached. In those

cases, the QTRC Trace API that writes trace data can be called directly, without using the

QtrcGetActiveLevel() API and checking the variable as described above.

Character Data Processing

The QTRC Trace APIs do not convert character data as it is being processed. Hence, it is important to

understand and follow certain guidelines, when using character data on various parameters of the QTRC

Trace APIs:

v Character data should be limited to the invariant character set.

v Character data should not contain control characters such as newline, line feed, or carriage return.

v Component names should not contain lowercase a through z. Application component names should

contain an abbreviated company name along with the application name. Component names starting

with an asterisk (*) are reserved for the operating system. Component names starting with Q are

reserved for IBM®

licensed programs.

v Subcomponent names should not contain lowercase a through z.

v Mixed-byte strings that contain DBCS characters should not be used for a Component name or a

Subcomponent name.

v The format string used by QtrcWriteTextPrintF(), QtrcWriteTextPPrintF(), and QtrcWriteTextVPrintF()

APIs is assumed to be in the CCSID of the job.

v When an application is given character data that originates from outside the application, the preferred

method for tracing that character data is through the QtrcWriteHexDumpF() API.


Header Files for UNIX-Type Functions

Programs using the UNIX®

-type functions must include one or more header files that contain information

needed by the functions, such as:

v Macro definitions

v Data type definitions

v Structure definitions

v Function prototypes


#TOP_OF_PAGE

aplist.htm

The header files are provided in the QSYSINC library, which is optionally installable. Make sure

QSYSINC is on your system before compiling programs that use these header files. For information about

installing the QSYSINC library, see Include files and the QSYSINC library.

The table below shows the file and member name in the QSYSINC library for each header file used by

the UNIX-type APIs in this publication.

Name of Header File Name of File in QSYSINC Name of Member

arpa/inet.h ARPA INET

arpa/nameser.h ARPA NAMESER

bse.h H BSE

bsedos.h H BSEDOS

bseerr.h H BSEERR

dirent.h H DIRENT

errno.h H ERRNO

fcntl.h H FCNTL

grp.h H GRP

inttypes.h H INTTYPES

limits.h H LIMITS

netdbh.h H NETDB

netinet/icmp6.h NETINET ICMP6

net/if.h NET IF

netinet/in.h NETINET IN

netinet/ip_icmp.h NETINET IP_ICMP

netinet/ip.h NETINET IP

netinet/ip6.h NETINET IP6

netinet/tcp.h NETINET TCP

netinet/udp.h NETINET UDP

netns/idp.h NETNS IDP

netns/ipx.h NETNS IPX

netns/ns.h NETNS NS

netns/sp.h NETNS SP

net/route.h NET ROUTE

nettel/tel.h NETTEL TEL

os2.h H OS2

os2def.h H OS2DEF

pwd.h H PWD

Qlg.h H QLG

qp0lchsg.h H QP0LCHSG

qp0lflop.h H QP0LFLOP

qp0ljrnl.h H QP0LJRNL

qp0lror.h H QP0LROR

qp0lrro.h H QP0LRRO

qp0lrtsg.h H QP0LRTSG



qp0lscan.h H QP0LSCAN

Qp0lstdi.h H QP0LSTDI

qp0wpid.h H QP0WPID

qp0zdipc.h H QP0ZDIPC

qp0zipc.h H QP0ZIPC

qp0zolip.h H QP0ZOLIP

qp0zolsm.h H QP0ZOLSM

qp0zripc.h H QP0ZRIPC

qp0ztrc.h H QP0ZTRC

qp0ztrml.h H QP0ZTRML

qp0z1170.h H QP0Z1170

qsoasync.h H QSOASYNC

qtnxaapi.h H QTNXAAPI

qtnxadtp.h H QTNXADTP

qtomeapi.h H QTOMEAPI

qtossapi.h H QTOSSAPI

resolv.h H

RESOLV

semaphore.h H SEMAPHORE

signal.h H SIGNAL

spawn.h H SPAWN

ssl.h H SSL

sys/errno.h H ERRNO

sys/ioctl.h SYS IOCTL

sys/ipc.h SYS IPC

sys/layout.h

SYS

LAYOUT

sys/limits.h H LIMITS

sys/mman.h SYS

MMAN

sys/msg.h SYS MSG

sys/param.h SYS PARAM

sys/resource.h SYS RESOURCE

sys/sem.h SYS SEM

sys/setjmp.h SYS SETJMP

sys/shm.h SYS SHM

sys/signal.h SYS SIGNAL

sys/socket.h SYS SOCKET

sys/stat.h SYS STAT

sys/statvfs.h SYS STATVFS

sys/time.h SYS TIME

sys/types.h SYS TYPES

sys/uio.h SYS UIO

sys/un.h SYS UN



sys/wait.h SYS WAIT

ulimit.h H ULIMIT

unistd.h H UNISTD

utime.h H UTIME

You can display a header file in QSYSINC by using one of the following methods:

v Using your editor. For example, to display the unistd.h header file using the Source Entry Utility

editor, enter the following command:

STRSEU SRCFILE(QSYSINC/H) SRCMBR(UNISTD) OPTION(5)

v Using the Display Physical File Member command. For example, to display the sys/stat.h header file,

enter the following command:

DSPPFM FILE(QSYSINC/SYS) MBR(STAT)

You can print a header file in QSYSINC by using one of the following methods:

v Using your editor. For example, to print the unistd.h header file using the Source Entry Utility editor,

enter the following command:

STRSEU SRCFILE(QSYSINC/H) SRCMBR(UNISTD) OPTION(6)

v Using the Copy File command. For example, to print the sys/stat.h header file, enter the following

command:

CPYF FROMFILE(QSYSINC/SYS) TOFILE(*PRINT) FROMMBR(STAT)

Symbolic links to these header files are also provided in directory /QIBM/include.

Top | UNIX-Type APIs | APIs by category

Errno Values for UNIX-Type Functions

Programs using the UNIX®

-type functions may receive error information as errno values. The possible

values returned are listed here in ascending errno value sequence.

Name Value Text Details

EDOM 3001 A domain error occurred in a math

function.

ERANGE 3002 A range error occurred.

ETRUNC 3003 Data was truncated on an input,

output, or update operation.

ENOTOPEN 3004 File is not open. You attempted to do an operation that

required the file to be open.

ENOTREAD 3005 File is not opened for read operations. You tried to read a file that is not open

for read operations.

EIO 3006 Input/output error. A physical I/O error occurred or a

referenced object was damaged.

ENODEV 3007 No such device.

ERECIO 3008 Cannot get single character for files

opened for record I/O.

The file that was specified is open for

record I/O and you attempted to read it

as a stream file.


#TOP_OF_PAGE

unix.htm

aplist.htm


ENOTWRITE 3009 File is not opened for write

operations.

You tried to update a file that has not

been opened for write operations.

ESTDIN 3010 The stdin stream cannot be opened.

ESTDOUT 3011 The stdout stream cannot be opened.

ESTDERR 3012 The stderr stream cannot be opened.

EBADSEEK 3013 The positioning parameter in fseek is

not correct.

EBADNAME 3014 The object name specified is not

correct.

EBADMODE 3015 The type variable specified on the

open function is not correct.

The mode that you attempted to open

the file in is not correct.

EBADPOS 3017 The position specifier is not correct.

ENOPOS 3018 There is no record at the specified

position.

You attempted to position to a record

that does not exist in the file.

ENUMMBRS 3019 Attempted to use ftell on multiple

members.

Remove all but one member from the

file.

ENUMRECS 3020 The current record position is too

long for ftell.

EINVAL 3021 The value specified for the argument

is not correct.

A function was passed incorrect

argument values, or an operation was

attempted on an object and the operation

specified is not supported for that type

of object.

EBADFUNC 3022 Function parameter in the signal

function is not set.

ENOENT 3025 No such path or directory. The directory or a component of the path

name specified does not exist.

ENOREC 3026 Record is not found.

EPERM 3027 The operation is not permitted. You must have appropriate privileges or

be the owner of the object or other

resource to do the requested operation.

EBADDATA 3028 Message data is not valid. The message data that was specified for

the error text is not correct.

EBUSY 3029 Resource busy. An attempt was made to use a system

resource that is not available at this time.

EBADOPT 3040 Option specified is not valid.

ENOTUPD 3041 File is not opened for update

operations.

ENOTDLT 3042 File is not opened for delete

operations.

EPAD 3043 The number of characters written is

shorter than the expected record

length.

The length of the record is longer than

the buffer size that was specified. The

data written was padded to the length of

the record.

EBADKEYLN 3044 A length that was not valid was

specified for the key.

You attempted a record I/O against a

keyed file. The key length that was

specified is not correct.



EPUTANDGET 3080

A write operation should not

immediately follow a read operation.

EGETANDPUT 3081

A read operation should not

immediately follow a write operation.

EIOERROR 3101 A nonrecoverable I/O error occurred.

EIORECERR 3102 A recoverable I/O error occurred.

EACCES 3401 Permission denied. An attempt was made to access an object

in a way forbidden by its object access

permissions.

ENOTDIR 3403 Not a directory. A component of the specified path name

existed, but it was not a directory when

a directory was expected.

ENOSPC 3404 No space is available. The requested operations required

additional space on the device and there

is no space left. This could also be

caused by exceeding the user profile

storage limit when creating or

transferring ownership of an object.

EXDEV 3405 Improper link. A link to a file on another file system

was attempted.

EAGAIN 3406 Operation would have caused the

process to be suspended.

EWOULDBLOCK 3406 Operation would have caused the

process to be suspended.

EINTR 3407 Interrupted function call.

EFAULT 3408 The address used for an argument

was not correct.

In attempting to use an argument in a

call, the system detected an address that

is not valid.

ETIME 3409 Operation timed out.

ENXIO 3415 No such device or address.

ECLOSED 3417 Socket closed.

EAPAR 3418 Possible APAR condition or hardware

failure.

ERECURSE 3419 Recursive attempt rejected.

EADDRINUSE 3420 Address already in use.

EADDRNOTAVAIL 3421 Address is not available.

EAFNOSUPPORT 3422 The type of socket is not supported in

this protocol family.

EALREADY 3423 Operation is already in progress.

ECONNABORTED 3424 Connection ended abnormally.

ECONNREFUSED 3425 A remote host refused an attempted

connect operation.

ECONNRESET 3426 A connection with a remote socket

was reset by that socket.

EDESTADDRREQ 3427 Operation requires destination

address.



EHOSTDOWN 3428 A remote host is not available.

EHOSTUNREACH 3429 A route to the remote host is not

available.

EINPROGRESS 3430 Operation in progress.

EISCONN 3431 A connection has already been

established.

EMSGSIZE 3432 Message size is out of range.

ENETDOWN 3433 The network is currently not

available.

ENETRESET 3434 A socket is connected to a host that is

no longer available.

ENETUNREACH 3435 Cannot reach the destination

network.

ENOBUFS 3436 There is not enough buffer space for

the requested operation.

ENOPROTOOPT 3437 The protocol does not support the

specified option.

ENOTCONN 3438 Requested operation requires a

connection.

ENOTSOCK 3439 The specified descriptor does not

reference a socket.

ENOTSUP 3440 Operation is not supported. The operation, though supported in

general, is not supported for the

requested object or the requested

arguments.

EOPNOTSUPP 3440 Operation is not supported. The operation, though supported in

general, is not supported for the

requested object or the requested

arguments.

EPFNOSUPPORT 3441 The socket protocol family is not

supported.

EPROTONOSUPPORT 3442 No protocol of the specified type and

domain exists.

EPROTOTYPE 3443 The socket type or protocols are not

compatible.

ERCVDERR 3444 An error indication was sent by the

peer program.

ESHUTDOWN 3445 Cannot send data after a shutdown.

ESOCKTNOSUPPORT 3446 The specified socket type is not

supported.

ETIMEDOUT 3447 A remote host did not respond within

the timeout period.

EUNATCH 3448 The protocol required to support the

specified address family is not

available at this time.



EBADF 3450 Descriptor is not valid. A file descriptor argument was out of

range, referred to a file that was not

open, or a read or write request was

made to a file that is not open for that

operation.

EMFILE 3452 Too many open files for this process. An attempt was made to open more files

than allowed by the value of

OPEN_MAX. The value of OPEN_MAX

can be retrieved using the sysconf()

function.

ENFILE 3453 Too many open files in the system. A system limit has been reached for the

number of files that are allowed to be

concurrently open in the system.

EPIPE 3455 Broken pipe.

ECANCEL 3456 Operation cancelled.

EEXIST 3457 Object exists. The object specified already exists and

the specified operation requires that it

not exist.

EDEADLK 3459 Resource deadlock avoided. An attempt was made to lock a system

resource that would have resulted in a

deadlock situation. The lock was not

obtained.

ENOMEM 3460 Storage allocation request failed. A function needed to allocate storage,

but no storage is available.

EOWNERTERM 3462 The synchronization object no longer

exists because the owner is no longer

running.

The process that had locked the mutex is

no longer running, so the mutex was

deleted.

EDESTROYED 3463 The synchronization object was

destroyed, or the object no longer

exists.

ETERM 3464 Operation was terminated.

ENOENT1 3465 No such file or directory. A component of a specified path name

did not exist, or the path name was an

empty string.

ENOEQFLOG 3466 Object is already linked to a dead

directory.

The link as a dead option was specified,

but the object is already marked as dead.

Only one dead link is allowed for an

object.

EEMPTYDIR 3467 Directory is empty. A directory with entries of only dot and

dot-dot was supplied when a nonempty

directory was expected.

EMLINK 3468 Maximum link count for a file was

exceeded.

An attempt was made to have the link

count of a single file exceed LINK_MAX.

The value of LINK_MAX can be

determined using the pathconf() or the

fpathconf() function.

ESPIPE 3469 Seek request is not supported for

object.

A seek request was specified for an

object that does not support seeking.

ENOSYS 3470 Function not implemented. An attempt was made to use a function

that is not available in this

implementation for any object or any

arguments.



EISDIR 3471 Specified target is a directory. The path specified named a directory

where a file or object name was

expected.

EROFS 3472 Read-only file system. You have attempted an update operation

in a file system that only supports read

operations.

EC2 3473 C2 pointer validation error.

EUNKNOWN 3474 Unknown system state. The operation failed because of an

unknown system state. See any messages

in the job log and correct any errors that

are indicated, then retry the operation.

EITERBAD 3475 Iterator is not valid.

EITERSTE 3476 Iterator is in wrong state for

operation.

EHRICLSBAD 3477 HRI class is not valid.

EHRICLBAD 3478 HRI subclass is not valid.

EHRITYPBAD 3479 HRI type is not valid.

ENOTAPPL 3480 Data requested is not applicable.

EHRIREQTYP 3481 HRI request type is not valid.

EHRINAMEBAD 3482 HRI resource name is not valid.

EDAMAGE 3484 A damaged object was encountered.

ELOOP 3485 A loop exists in the symbolic links. This error is issued if the number of

symbolic links encountered is more than

POSIX_SYMLOOP (defined in the

limits.h header file). Symbolic links are

encountered during resolution of the

directory or path name.

ENAMETOOLONG 3486 A path name is too long. A path name is longer than PATH_MAX

characters or some component of the

name is longer than NAME_MAX

characters while _POSIX_NO_TRUNC is

in effect. For symbolic links, the length of

the name string substituted for a

symbolic link exceeds PATH_MAX. The

PATH_MAX and NAME_MAX values

can be determined using the pathconf()

function.

ENOLCK 3487 No locks are available. A system-imposed limit on the number

of simultaneous file and record locks was

reached, and no more were available at

that time.

ENOTEMPTY 3488 Directory is not empty. You tried to remove a directory that is

not empty. A directory cannot contain

objects when it is being removed.

ENOSYSRSC 3489 System resources are not available.

ECONVERT 3490 Conversion error. One or more characters could not be

converted from the source CCSID to the

target CCSID.

E2BIG 3491 Argument list is too long.



EILSEQ 3492 Conversion stopped due to input

character that does not belong to the

input codeset.

ETYPE 3493 Object type mismatch. The type of the object referenced by a

descriptor does not match the type

specified on the interface.

EBADDIR 3494 Attempted to reference a directory

that was not found or was destroyed.

EBADOBJ 3495 Attempted to reference an object that

was not found, was destroyed, or was

damaged.

EIDXINVAL 3496 Data space index used as a directory

is not valid.

ESOFTDAMAGE 3497 Object has soft damage.

ENOTENROLL 3498 User is not enrolled in system

distribution directory.

You attempted to use a function that

requires you to be enrolled in the system

distribution directory and you are not.

EOFFLINE 3499 Object is suspended. You have attempted to use an object that

has had its data saved and the storage

associated with it freed. An attempt to

retrieve the object’s data failed. The

object’s data cannot be used until it is

successfully restored. The object’s data

was saved and freed either by saving the

object with the STG(*FREE) parameter, or

by calling an API.

EROOBJ 3500 Object is read-only. You have attempted to update an object

that can be read only.

EEAHDDSI 3501 Hard damage on extended attribute

data space index.

EEASDDSI 3502 Soft damage on extended attribute

data space index.

EEAHDDS 3503 Hard damage on extended attribute

data space.

EEASDDS 3504 Soft damage on extended attribute

data space.

EEADUPRC 3505 Duplicate extended attribute record.

ELOCKED 3506 Area being read from or written to is

locked.

The read or write of an area conflicts

with a lock held by another process.

EFBIG 3507 Object too large. The size of the object would exceed the

system allowed maximum size.

EIDRM 3509 The semaphore, shared memory, or

message queue identifier is removed

from the system.

ENOMSG 3510 The queue does not contain a

message of the desired type and

(msgflg logically ANDed with

IPC_NOWAIT).

EFILECVT 3511 File ID conversion of a directory

failed.

To recover from this error, run the

Reclaim Storage (RCLSTG) command as

soon as possible.



EBADFID 3512 A file ID could not be assigned when

linking an object to a directory.

The file ID table is missing or damaged.

To recover from this error, run the

Reclaim Storage (RCLSTG) command as

soon as possible.

ESTALE 3513 File or object handle rejected by

server.

ESRCH 3515 No such process.

ENOTSIGINIT 3516 Process is not enabled for signals. An attempt was made to call a signal

function under one of the following

conditions:

v The signal function is being called for

a process that is not enabled for

asynchronous signals.

v The signal function is being called

when the system signal controls have

not been initialized.

ECHILD 3517 No child process.

EBADH 3520 Handle is not valid.

ETOOMANYREFS 3523 The operation would have exceeded

the maximum number of references

allowed for a descriptor.

ENOTSAFE 3524 Function is not allowed. Function is not allowed in a job that is

running with multiple threads.

EOVERFLOW 3525 Object is too large to process. The object’s data size exceeds the limit

allowed by this function.

EJRNDAMAGE 3526 Journal is damaged. A journal or all of the journal’s attached

journal receivers are damaged, or the

journal sequence number has exceeded

the maximum value allowed. This error

occurs during operations that were

attempting to send an entry to the

journal.

EJRNINACTIVE 3527 Journal is inactive. The journaling state for the journal is

*INACTIVE. This error occurs during

operations that were attempting to send

an entry to the journal.

EJRNRCVSPC 3528 Journal space or system storage error. The attached journal receiver does not

have space for the entry because the

storage limit has been exceeded for the

system, the object, the user profile, or the

group profile. This error occurs during



EJRNRMT 3529 Journal is remote. The journal is a remote journal. Journal

entries cannot be sent to a remote

journal. This error occurs during





ENEWJRNRCV 3530 New journal receiver is needed. A new journal receiver must be attached

to the journal before entries can be

journaled. This error occurs during



ENEWJRN 3531 New journal is needed. The journal was not completely created,

or an attempt to delete it did not

complete successfully. This error occurs

during operations that were attempting

to start or end journaling, or were

attempting to send an entry to the

journal.

EJOURNALED 3532 Object already journaled. A start journaling operation was

attempted on an object that is already

being journaled.

EJRNENTTOOLONG 3533 Entry is too large to send. The journal entry generated by this

operation is too large to send to the

journal.

EDATALINK 3534 Object is a datalink object.

ENOTAVAIL 3535 Independent Auxiliary Storage Pool

(ASP) is not available.

The independent ASP is in Vary

Configuration (VRYCFG) or Reclaim

Storage (RCLSTG) processing. To recover

from this error, wait until processing has

completed for the independent ASP.

ENOTTY 3536 I/O control operation is not

appropriate.

EFBIG2 3540 Attempt to write or truncate file past

its sort file size limit.

ETXTBSY 3543 Text file busy. An attempt was made to execute an

i5/OS®

PASE program that is currently

open for writing, or an attempt has been

made to open for writing an i5/OS PASE

program that is being executed.

EASPGRPNOTSET 3544 ASP group not set for thread.

ERESTART 3545 A system call was interrupted and

may be restarted.

ESCANFAILURE 3546 Object had scan failure. An object has been marked as a scan

failure due to processing by an exit

program associated with the scan-related

integrated file system exit points.

Top | UNIX-Type APIs | APIs by category

Code license and disclaimer information

IBM grants you a nonexclusive copyright license to use all programming code examples from which you

can generate similar function tailored to your own specific needs.

SUBJECT TO ANY STATUTORY WARRANTIES WHICH CANNOT BE EXCLUDED, IBM, ITS

PROGRAM DEVELOPERS AND SUPPLIERS MAKE NO WARRANTIES OR CONDITIONS EITHER

EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OR


#TOP_OF_PAGE

unix.htm

aplist.htm

CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND

NON-INFRINGEMENT, REGARDING THE PROGRAM OR TECHNICAL SUPPORT, IF ANY.

UNDER NO CIRCUMSTANCES IS IBM, ITS PROGRAM DEVELOPERS OR SUPPLIERS LIABLE FOR

ANY OF THE FOLLOWING, EVEN IF INFORMED OF THEIR POSSIBILITY:

1. LOSS OF, OR DAMAGE TO, DATA;

2. DIRECT, SPECIAL, INCIDENTAL, OR INDIRECT DAMAGES, OR FOR ANY ECONOMIC

CONSEQUENTIAL DAMAGES; OR

3. LOST PROFITS, BUSINESS, REVENUE, GOODWILL, OR ANTICIPATED SAVINGS.

SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF DIRECT,

INCIDENTAL, OR CONSEQUENTIAL DAMAGES, SO SOME OR ALL OF THE ABOVE LIMITATIONS

OR EXCLUSIONS MAY NOT APPLY TO YOU.


Appendix. Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in other countries.

Consult your local IBM representative for information on the products and services currently available in

your area. Any reference to an IBM product, program, or service is not intended to state or imply that

only that IBM product, program, or service may be used. Any functionally equivalent product, program,

or service that does not infringe any IBM intellectual property right may be used instead. However, it is

the user’s responsibility to evaluate and verify the operation of any non-IBM product, program, or

service.

IBM may have patents or pending patent applications covering subject matter described in this

document. The furnishing of this document does not grant you any license to these patents. You can send

license inquiries, in writing, to:

IBM Director of Licensing

IBM Corporation

North Castle Drive

Armonk, NY 10504-1785

U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property

Department in your country or send inquiries, in writing, to:

IBM World Trade Asia Corporation

Licensing

2-31 Roppongi 3-chome, Minato-ku

Tokyo 106-0032, Japan

The following paragraph does not apply to the United Kingdom or any other country where such

provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION

PROVIDES THIS PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS

OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF

NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some

states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this

statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically

made to the information herein; these changes will be incorporated in new editions of the publication.

IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this

publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in

any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of

the materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without

incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the

exchange of information between independently created programs and other programs (including this

one) and (ii) the mutual use of the information which has been exchanged, should contact:

© Copyright IBM Corp. 1998, 2008 231

IBM Corporation

Software Interoperability Coordinator, Department YBWA

3605 Highway 52 N

Rochester, MN 55901

U.S.A.

Such information may be available, subject to appropriate terms and conditions, including in some cases,

payment of a fee.

The licensed program described in this document and all licensed material available for it are provided

by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement,

IBM License Agreement for Machine Code, or any equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, the

results obtained in other operating environments may vary significantly. Some measurements may have

been made on development-level systems and there is no guarantee that these measurements will be the

same on generally available systems. Furthermore, some measurements may have been estimated through

extrapolation. Actual results may vary. Users of this document should verify the applicable data for their

specific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, their

published announcements or other publicly available sources. IBM has not tested those products and

cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM

products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of

those products.

All statements regarding IBM’s future direction or intent are subject to change or withdrawal without

notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily business operations. To illustrate

them as completely as possible, the examples include the names of individuals, companies, brands, and

products. All of these names are fictitious and any similarity to the names and addresses used by an

actual business enterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which illustrate programming

techniques on various operating platforms. You may copy, modify, and distribute these sample programs

in any form without payment to IBM, for the purposes of developing, using, marketing or distributing

application programs conforming to the application programming interface for the operating platform for

which the sample programs are written. These examples have not been thoroughly tested under all

conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these

programs.

Each copy or any portion of these sample programs or any derivative work, must include a copyright

notice as follows:

© (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. ©

Copyright IBM Corp. _enter the year or years_. All rights reserved.

If you are viewing this information softcopy, the photographs and color illustrations may not appear.

Programming interface information

This API descriptions publication documents intended Programming Interfaces that allow the customer to

write programs to obtain the services of IBM i5/OS.


Trademarks

The following terms are trademarks of International Business Machines Corporation in the United States,

other countries, or both:

Advanced 36Advanced Function PresentationAdvanced Peer-to-Peer NetworkingAFPAIXAnyNetAS/400BCOCAC/400COBOL/400Common User AccessCUADB2DB2 Universal DatabaseDistributed Relational Database ArchitectureDominoDPIDRDAEnterprise Storage ServereServerFlashCopyGDDMi5/OSIBMIBM (logo)InfoColorInfoprintIntegrated Language EnvironmentIntelligent Printer Data StreamIPDSLotusLotus NotesMO:DCAMVSNet.DataNetServerNotesOfficeVisionOperating System/2Operating System/400OS/2OS/400PartnerWorldPOWER5+PowerPCPrint Services FacilityPrintManagerPROFSRISC System/6000RPG/400RS/6000

Appendix. Notices 233

SAASecureWaySOMSystem iSystem i5System Object ModelSystem/36System/38System/390TotalStorageVisualAgeWebSpherexSeriesz/OS

Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or trademarks

of Adobe Systems Incorporated in the United States, and/or other countries.

Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the

United States, other countries, or both.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other

countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Other company, product, or service names may be trademarks or service marks of others.

Terms and conditions

Permissions for the use of these publications is granted subject to the following terms and conditions.

Personal Use: You may reproduce these publications for your personal, noncommercial use provided that

all proprietary notices are preserved. You may not distribute, display or make derivative works of these

publications, or any portion thereof, without the express consent of IBM.

Commercial Use: You may reproduce, distribute and display these publications solely within your

enterprise provided that all proprietary notices are preserved. You may not make derivative works of

these publications, or reproduce, distribute or display these publications or any portion thereof outside

your enterprise, without the express consent of IBM.

Except as expressly granted in this permission, no other permissions, licenses or rights are granted, either

express or implied, to the publications or any information, data, software or other intellectual property

contained therein.

IBM reserves the right to withdraw the permissions granted herein whenever, in its discretion, the use of

the publications is detrimental to its interest or, as determined by IBM, the above instructions are not

being properly followed.

You may not download, export or re-export this information except in full compliance with all applicable

laws and regulations, including all United States export laws and regulations.

IBM MAKES NO GUARANTEE ABOUT THE CONTENT OF THESE PUBLICATIONS. THE

PUBLICATIONS ARE PROVIDED ″AS-IS″ AND WITHOUT WARRANTY OF ANY KIND, EITHER


EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF

MERCHANTABILITY, NON-INFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE.

Appendix. Notices 235

��

Printed in USA

system i: programming problem management...

Documents