Subfile APIs in your service program manipulate the records from a subfile that are displayed in the iSeries Table Web component on a JSP page.
The subfile is an object type *USRSPC in the QTEMP library of the iSeries job in the current session. This space must have the same name as the name of the table Web component on the JSP. Before you can perform any operations on the subfile, such as adding a record, you must first call the QdtsInitSF API, to initialize the subfile, in the QDTSSFL service program. This API creates the space with the given in the job's QTEMP library. When the JSP page with the table Web component is first loaded, and before it is displayed, it invokes the INIT procedure of the service program that is defined on the Parameters tab of the table's attribute view. You would put this procedure, a call to the QdtsInitSF API to create and initialize the subfile space, followed by a call to the QdtsAppendSF API to add records to the subfile.
Note that the INIT procedure is only called the first time the JSP page is displayed. It is not called when the JSP page is displayed again.
If you need to change the contents of the subfile, you make those changes in the Web interactions before the JSP page with the subfile is displayed. Before the JSP page is displayed, it always retrieves the current data from the user space.
The subfile API names and the operation that each API performs are described below.
API name | API operation |
---|---|
QdtsAppendSF | Add a record |
QdtsChainSF | Chain to a record |
QdtsClearSF | Clear the subfile |
QdtsCountSF | Return a count of subfile records |
QdtsDeleteSF | Delete a subfile record |
QdtsInitSF | Initialize the subfile |
QdtsReadcSF | Read a selected record |
QdtsSetDspAtrSF | Set display attributes for each subfile cell |
QdtsSetNxtChgSF | Set the next changed record |
QdtsSetRcdNbrSF | Set the current record number |
QdtsUpdateSF | Update a record |
To use the APIs, you need to ensure that your service program has been bound to the subfile service program QDTSSFL in library QSYS on your iSeries host. Effective with V5R3, this service program is included in library QSYS. For V5R2 and V5R1, QDTSSFL is packaged in PTF SI09790 and PTF SI09791, respectively. You must apply the PTF that is specific to your release of the operating system to obtain service program QDTSSFL.
For the development environment:
The following sections describe each of the subfile APIs and includes the syntax, parameters, program prototype, and an example for each. (See COBOL program example using subfile APIs for an example of how the subfile APIs are coded in an ILE COBOL program.)
Use this API to add a record to the subfile. Records are added to the end of the subfile.
Since subfile records are inserted into a *USRSPC object, the limit to the number of records is determined by the maximum size of a *USRSPC object, and the length of the records being added. If the maximum is reached, then a value of -1 is returned when attempting to append a record.
Syntax:
CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++ Eval RC=QdtsAppendSF(SFLName: pRcd: length)
Parameters:
Prototype:
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ D append PR 10I 0 Extproc('QdtsAppendSF') D SFLName 10A Const D pRcd * Value D len 10I 0 Value
Example:
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ D append PR 10I 0 Extproc('QdtsAppendSF') D SFLName 10A Const D pRcd * Value D len 10I 0 Value D SFLName S Inz('SFL1') D Record DS D Name 20A D City 30A D RC S 10I 0 * CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++ Eval Name='Larry' Eval City='Pickering' Eval rc=append(SFLName: %Addr(Record): %Size(Record))
Use this API to retrieve a specific record from the subfile by passing the relative record number of the record you want.
Syntax:
CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++ Eval RC=QdtsChainSF(SFLName: pRcd: length: RRN)
Parameters:
Prototype:
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ D chain PR 10I 0 Extproc('QdtsChainSF') D SFLName 10A Const D pRcd * Value D len 10I 0 Value D rrn 10I 0 Value
Example:
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ D chain PR 10I 0 Extproc('QdtsChainSF') D SFLName 10A Const D pRcd * Value D len 10I 0 Value D rrn 10I 0 Value D SFLName S Inz('SFL1') D Record DS D Name 20A D City 30A D RC S 10I 0 D RRN S 10I 0 * CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++ Eval RRN = 3 Eval RC=chain(SFLName: %Addr(Record): %Size(Record): RRN) * Name = Donna (possibly) * City = Guelph (possibly)
Use this API to remove all records from the subfile. You can call this API if you are filling the subfile a page at time.
Syntax:
CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++ Eval RC=QdtsClearSF(SFLName)
Parameters:
Prototype:
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ D clear PR 10I 0 Extproc('QdtsClearSF') D SFLName 10A Const
Example:
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ D clear PR 10I 0 Extproc('QdtsClearSF') D SFLName 10A Const D RC S 10I 0 D SFLName S 10A Inz('SFL1') * CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++ Eval RC=clear(SFLName)
Syntax:
CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++ Eval count = QdtsCountSF(SFLName)
Parameters:
Prototype:
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ D getCount PR 10I 0 Extproc('QdtsCountSF') D SFLName 10A Const D count 10I 0
Example:
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ D getCount PR 10I 0 Extproc('QdtsCountSF') D SFLName 10A Const D count S 10I 0 D SFLName S 10A Inz('SFL1') * CL0N01Factor1+++++++Opcode&Extended-factor2+++++++++++++++++++++++++++++ Eval count =getCount(SFLName)
Syntax:
CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++ Eval RC = QdtsDeleteSF(SFLName:RRN)
Parameters:
Prototype:
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ D delrec PR 10I 0 Extproc('QdtsDeleteSF') D SFLName 10A Const D rrn 10I 0
Example:
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ D delrec PR 10I 0 Extproc('QdtsDeleteSF') D SFLName 10A Const D RRN 10I 0 D RC S 10I 0 D SFLName S 10A Inz('SFL1') * CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++ Eval RC=delrec(SFLName: 3)
Use this API to initialize the subfile for first time use. The call to this API is typically put in the INIT procedure that is called the first time that the JSP containing the subfile is to be displayed.
Syntax:
CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++ Eval RC=QdtsInitSF(SFLName: pReserved: length)
Parameters:
Prototype:
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ D initSF PR 10I 0 Extproc('QdtsInitSF') D SFLName 10A Const D pReserved * Value D len 10I 0 Value
Example:
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ D initSF PR 10I 0 Extproc('QdtsInitSF') D SFLName 10A Const D pReserved * Value D len 10I 0 Value D SFLName S Inz('SFL1') D rsvd S 10A D RC S 10I 0 * CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++ Eval RC=initSF(SFLName: %Addr(rsvd): %Size(Record))
Use this API to read a record that was selected in the subfile. Records in a subfile are selected by selecting the radio button or check box that is associated with each subfile record. In addition, if the subfile record has entry fields, check boxes, combo boxes, or text area Web components, and if the values of those iSeries Web components change, this API also returns those records.
Syntax:
CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++ Eval RRN=QdtsReadcSF(SFLName: pRcd: length: startRRN)
Parameters:
Prototype:
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ D readc PR 10I 0 Extproc('QdtsReadcSF') D SFLName 10A Const D pRcd * Value D len 10I 0 Value
Example:
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ D readc PR 10I 0 Extproc('QdtsReadcSF') D SFLName 10A Const D pRcd * Value D len 10I 0 Value D SFLName S Inz('SFL1') D Record DS D Name 20A D City 30A D RRN S 10I 0 * CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++ Eval RRN=readc(SFLName: %Addr(Record): %Size(Record)) * Name = Donna (possibly) * City = Guelph (possibly) * RRN = 3 (possibly)
Use this API to set display attributes for each cell of the subfile.
Syntax:
CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++ Eval RC=QdtsSetDspAtrSF(SFLName, RRN, ColNbr, Attribute, Length)
Parameters
To specify more than one attribute for a cell, make sure the attributes are delimited by a space. For example, "*PC *RI" specifies that the cell will have the cursor, and it will be in reverse image. If *NONE is specified along with other attributes, it has no effect.
You can also define your own display attribute. The following rules apply for user defined attributes:
Attribute | Applicable Web components |
*PC | Text entry, Text area |
*PR | All except image and label components, and the select column |
*RI | All |
*HI | All except image component and the select column |
*ND | All except the select column |
*UL | All except image component and the select column |
*NONE | All |
User defined | All |
Prototype:
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ D setAtr PR 10I 0 Extproc('QdtsSetDspAtrSF') D SFLName 10A Const D recordRRN 10I 0 Value D colNbr 10I 0 Value D style * Value D styleLen 10I 0 Value
Example:
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ D setAtr PR 10I 0 Extproc('QdtsSetDspAtrSF') D SFLName 10A Const D recordRRN 10I 0 Value D colNbr 10I 0 Value D style * Value D styleLen 10I 0 Value D* D limitWarn S 10A Inz('limitwarn') D ordersSFL S 10A Inz('ORDERSSFL') CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++ * If the balance is greater than the credit limit for * the record just read from the subfile (record number is in 'curRec') * set the style class for the balance column (column 3) to the limitwarn * class to hilite that column * In the style sheet style 'limitwarn' would be defined as follows: * * .limitwarn {color: red; background-color: yellow;} * C If balance > creditLimit C Eval rc = setAtr(ordersSFL: curRec: 3: limitWarn: C %Size(limitWarn) C EndIf
Use this API to set the next changed record in the subfile.
Syntax:
CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++ Eval RC=QdtsSetNxtChgSF(SFLName, RRN)
Parameters
Prototype:
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ D setNxtChg PR 10I 0 Extproc('QdtsSetNxtChgSF') D SFLName 10A Const D recordRRN 10I 0 Value
Example:
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ D setNxtChg PR 10I 0 Extproc('QdtsSetNxtChgSF') D SFLName 10A Const D recordRRN 10I 0 Value D* D limitWarn S 10A Inz('limitwarn') D ordersSFL S 10A Inz('ORDERSSFL') CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++ * If the option is not a '1', set the next change indicator so this * record will be read on a subsequent READC * set the style class for the balance column (column 3) to the limitwarn * class to hilite that column * In the style sheet style 'limitwarn' would be defined as follows: * C Eval rrn = readC(ordersSFL: sflRcd: %Size(sflRcd)) * C If opt <> '1' C Eval rc = setNxtChg(orderSFL: rrn) C EndIf
Use this API to set the current record number in the subfile. The subfile will position to the page that contains the record identified by RRN.
Syntax:
CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++ Eval RC=QdtsSetRcdNbrSF(SFLName, RRN)
Parameters
Prototype:
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ D setRcdNbr PR 10I 0 Extproc('QdtsSetRcdNbrSF') D SFLName 10A Const D recordRRN 10I 0 Value
Example:
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ D setRcdNbr PR 10I 0 Extproc('QdtsSetRcdNbrSF') D SFLName 10A Const D recordRRN 10I 0 Value * D ordersSFL S 10A Inz('ORDERSSFL') CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++ * Position the subfile to the first page * C Eval rc = setRcdNbr(orderSFL: 1)
Use this API to update an existing record in the subfile. It is not necessary to read the record before updating it.
Syntax:
CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++ Eval RC=QdtsUpdateSF(SFLName: pRcd: length, RRN)
Parameters
Prototype:
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ D update PR 10I 0 Extproc('QdtsUpdateSF') D SFLName 10A Const D pRcd * Value D len 10I 0 Value D rrn 10I 0 Value
Example:
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ D update PR 10I 0 Extproc('QdtsUpdateSF') D SFLName 10A Const D pRcd * Value D len 10I 0 Value D rrn 10I 0 Value D SFLName S Inz('SFL1') D Record DS D Name 20A D City 30A D RC S 10I 0 D RRN S 10I 0 * CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++ Eval Name = 'Donna' Eval City = 'Guelph' Eval RC = update(SFLName: %Addr(Record): %Size(Record): 3)
(C) Copyright IBM Corporation 1992, 2006. All Rights Reserved.