Register Debug View (QteRegisterDebugView) API

The Register Debug View (QteRegisterDebugView) API registers a view of a module, which allows a program to be debugged in terms of that view. An identifier to the view is returned on successful completion of the API to be used in subsequent view information APIs. A program is considered to be active under ILE debug only after at least one of its debug views is registered.

Views retrieved by the Retrieve Module Views (QteRetrieveModuleViews) API can be registered. This includes both ILE and OPM program views. OPM program views must have been created by the OPM CL, OPM COBOL, or OPM RPG compiler using the *SRCDBG or *LSTDBG option.

This API will also register JAVA class file views. In this case the input program type parameter must be *CLASS and the input qualified program name parameter must be a null-terminated JAVA class file name. The class path name of the file that contains the class file is returned in the returned library parameter.

If a request is made to register an already registered view, no error occurs. Instead, the previous ID is returned.

Note: Before registering views for a program again, it is recommended that all views for that program first be removed.

Authorities

The authorities required are dependent on the program type parameter. If the program type is *PGM or *SRVPGM, the authorities are as follows:

Program Authority

Either *SERVICE and *USE, or *CHANGE

Library Authority

*USE

If the program type is *CLASS, the authorities are as follows:

Class File Authority

*R

Required Parameter Group

View ID

OUTPUT; BINARY(4)

The returned ID of the successfully (or previously) registered debug view. The source debugger support supplies and maintains the view IDs. If no error is reported by the API, this value is used by the program in view ID input parameters that occur on subsequent debugger APIs.

Number of lines

OUTPUT; BINARY(4)

The number of lines of text in the view.

Returned library

OUTPUT; CHAR(10) or CHAR(*)

The format of this parameter is dependent on the program type parameter. If the program type is *PGM or *SRVPGM, the format of this parameter is OUTPUT CHAR(10) as follows:

The library where the program was found. This is useful when *LIBL or *CURLIB is specified for the program library.

If the program type is *CLASS, the format of this parameter is OUTPUT CHAR(*) as follows:

Class path name information for the requested class file. For more information, see Format of JAVA Returned Library Parameter.

View timestamp

OUTPUT; CHAR(13)

The date and time the view was created. If this time is greater than the time obtained from the Retrieve Module Views API, the view may not be the same as the previous one. Users should run the Retrieve Module Views API before registering the view. The value is the American National Standard 13-character timestamp CYYMMDDHHMMSS format, where:

C

Century, where 0 indicates years 19xx and 1 indicates years 20xx.

YY

Year

MM

Month

HH

Hour

MM

Minute

SS

Second

Qualified program name

INPUT; CHAR(20) or CHAR(*)

The format of this parameter is dependent on the program type parameter. If the program type is *PGM or *SRVPGM, the format of this parameter is as follows:

The name of a program for which a view is to be registered. The first 10 characters contain the program name. The second 10 characters contain the name of the library where the program is located. The following special values may be used for the library name:

*CURLIB

The job's current library.

*LIBL

The library list.

If the program type is *CLASS, the format of this parameter is as follows:

The null-terminated class file name of the JAVA class to register.

Program type

INPUT; CHAR(10)

The type of program for which a view is to be registered. This is the object type of the program object. The valid values are:

*PGM

ILE or OPM program

*SRVPGM

ILE service program

*CLASS

JAVA class file

Module name

INPUT; CHAR(10) or BINARY(4)

The format of this parameter is dependent on the program type parameter. If the program type is *PGM or *SRVPGM, the format of this parameter is as follows:

The name of a module for which a view is to be registered. The module name should be left-justified. The module name parameter must be specified as all blanks for OPM programs.

Information for this parameter is available by using the Retrieve Module Views API to retrieve available module names for a specified program.

If the program type is *CLASS, the format of this parameter is as follows:

The module name parameter must contain a 4-byte binary field. This field contains the number of bytes provided in the returned library parameter for returned JAVA class path name information. The value specified in this parameter must be at least 8 bytes.

View number

INPUT; BINARY(4)

The number of a view to be registered for subsequent view information and debug command APIs. If -1 is specified, the statement view is registered. The value -1 is a shortcut to allow the registering of this view without going through the Retrieve Module Views API to obtain the number.

Information for this parameter is available by using the Retrieve Module Views API to retrieve available view numbers for modules associated with a specific program.

Error code

I/O; CHAR(*)

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

Format of JAVA Returned Library Parameter

When the program type parameter is *CLASS, class path name information is returned in the returned library parameter. The following table shows the format of the returned library parameter when JAVA class file view information is registered. For more information on the fields, see Field Descriptions.

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Bytes returned
4	4	BINARY(4)	Bytes available
8	8	BINARY(4)	Offset to class path name
C	C	BINARY(4)	Length of class path name
		CHAR(*)	Class path name

Field Descriptions

Bytes available. The number of bytes available to be returned in the returned library parameter. If the bytes available value is larger than the bytes provided value passed in the module name parameter, the API should be called again with a value that is at least as large as the bytes available. If the space provided is not large enough, the string space is filled with as many characters of the class path name as will fit.

Bytes returned. The number of bytes returned in the returned library parameter.

Class path name. The path name of the file that contains the class file that was retrieved.

Length of class path name. The length of the class path name returned.

Offset to class path name. The offset from the start of the returned library parameter to the class path name.

Error Messages

CPF3CF1 E

Error code parameter not valid.

CPF3CF2 E

Error(s) occurred during running of &1 API.

CPF9541 E

Not in debug mode.

CPF9542 E

View not found.

CPF9549 E

Error addressing API parameter.

CPF954F E

Module &1 not found.

CPF955F E

Program &1 not a bound program.

CPF9562 E

Module &1 cannot be debugged.

CPF9584 E

OPM program &1 cannot be added to ILE debug environment.

CPF9585 E

Program &1 already active in OPM debug environment.

CPF9587 E

Module name value &1 not valid.

CPF9588 E

OPM source cannot be accessed.

CPF9591 E

Value specified in module name parameter is not valid.

CPF9592 E

Class file not found.

CPF9593 E

Not authorized to class file.

CPF9594 E

JAVA class file not available.

CPF9599 E

Class file cannot be debugged.

CPF9801 E

Object &2 in library &3 not found.

CPF9802 E

Not authorized to object &2 in &3.

CPF9803 E

Cannot allocate object &2 in library &3.

CPF9809 E

Library &1 cannot be accessed.

CPF9810 E

Library &1 not found.

CPF9820 E

Not authorized to use library &1.