Subfile APIs

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.

Note: Since the subfile is an object in QTEMP, you should not have two subfile components with the same name in your application.

The subfile API names and the operation that each API performs are described below.

Table 1. Subfile APIs - names and operations
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

Subfile service program QDTSSFL

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:

  1. Bind the user program that makes the Table Web component API call, to library_name/QDTSSFL.SRVPGM.
Note: For users who bound their service programs with an earlier version:
  1. All existing programs that are bound to the QSYS/QDTSSFL have to be rebound to the new service program library_name/QDTSSFL.

Subfile API operations and names

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.)

Note: For all subfile APIs, a return code of -2 is returned is the user space has not been created. For example, this return code is returned if you attempt to append a record to the subfile but you have not yet called the QdtsInitSF API.

Add a record to the subfile - QdtsAppendSF

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))

Chain to a specific subfile record - QdtsChainSF

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)

Clear the subfile - QdtsClearSF

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)

Return count of the number of subfile records - QdtsCountSF

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)

Delete a subfile record - QdtsDeleteSF

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)

Initialize the subfile - QdtsInitSF

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))

Read a selected record - QdtsReadcSF

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)

Set cell attributes - QdtsSetDspAtrSF

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

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

Set the next changed record - QdtsSetNxtChgSF

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

Set the current record number - QdtsSetRcdNbrSF

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)

Update a record - QdtsUpdateSF

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)