Create User Index
/*-------------------------------------------------------------------*/
/* */
/* Command . . : CRTUSRIDX */
/* Description : Create user index command */
/* Author . . : Carsten Flensburg */
/* Published . : Club Tech iSeries Programming Tips Newsletter */
/* Date . . . : September 23, 2004 */
/* */
/* */
/* Command processing API: */
/* QUSCRTUI Create user index Creates a user index object */
/* in either the user domain */
/* or the system domain. */
/* */
/* */
/* Programmer's notes: */
/* On pre-V5R2 systems the IDXSIZOPT parameter is not supported. */
/* */
/* An upcoming issue of APIs by Example will demonstrate the use */
/* of some of the user index APIs in RPG/IV. */
/* */
/* */
/* Compile options: */
/* */
/* CrtCmd Cmd( CRTUSRIDX ) */
/* Pgm( QUSCRTUI ) */
/* SrcMbr( CBX124X ) */
/* HlpPnlGrp( CBX124H ) */
/* HlpId( *CMD ) */
/* */
/*-------------------------------------------------------------------*/
Cmd Prompt( 'Create User Index' )
Parm USRIDX Q0001 +
Min( 1 ) +
Choice( *NONE ) +
Prompt( 'User index' 1 )
Parm EXTATR *Name 10 +
Dft( *NONE ) +
SpcVal(( *NONE ' ' )) +
Expr( *YES ) +
Prompt( 'Extended attribute' 2 )
Parm ENTLENATR *Char 1 +
Rstd( *YES ) +
Dft( *FIXED ) +
SpcVal(( *FIXED 'F' ) ( *VARYING 'V' )) +
Expr( *YES ) +
Prompt( 'Entry length attribute' 3 )
Parm ENTLEN *Int4 +
Range( 1 2000 ) +
SpcVal(( *SHORT 0 ) ( *MAX -1 )) +
Expr( *YES ) +
Prompt( 'Entry length' 4 )
Parm SEQ *Char 1 +
Rstd( *YES ) +
Dft( *NONE ) +
SpcVal(( *NONE '0' ) ( *KEYED '1' )) +
Expr( *YES ) +
Prompt( 'Sequence' 5 )
Parm KEYLEN *Int4 +
Range( 1 2000 ) +
Expr( *YES ) +
PmtCtl( P0001 ) +
Prompt( 'Key length' 6 )
Parm FORCE *Char 1 +
Rstd( *YES ) +
Dft( *NO ) +
SpcVal(( *NO '0' ) ( *YES '1' )) +
Expr( *YES ) +
Prompt( 'Force to auxiliary storage' 7 )
Parm IDXOPZ *Char 1 +
Rstd( *YES ) +
Dft( *RANDOM ) +
SpcVal(( *RANDOM '0' ) ( *SEQ '1' )) +
Expr( *YES ) +
Prompt( 'Index optimization' 8 )
Parm AUT *Name 10 +
Dft( *LIBCRTAUT ) +
SpcVal(( *LIBCRTAUT ) +
( *CHANGE ) +
( *ALL ) +
( *USE ) +
(*EXCLUDE )) +
Expr( *YES ) +
PmtCtl( *PMTRQS ) +
Prompt( 'Authority' 9 )
Parm TEXT *Char 50 +
Dft( *BLANK ) +
SpcVal(( *BLANK '' )) +
Expr( *YES ) +
Prompt( 'Text ''description''' 10 )
Parm REPLACE *Char 10 +
Rstd( *YES ) +
Dft( *YES ) +
SpcVal(( *YES ) ( *NO )) +
Expr( *YES ) +
PmtCtl( *PMTRQS ) +
Prompt( 'Replace' 11 )
Parm ERROR *Int4 +
Constant( 0 )
Parm DOMAIN *Char 10 +
Rstd( *YES ) +
Dft( *DEFAULT ) +
SpcVal(( *DEFAULT ) ( *SYSTEM ) ( *USER )) +
Expr( *YES ) +
PmtCtl( *PMTRQS ) +
Prompt( 'Domain' 12 )
Parm USGTRK *Char 1 +
Rstd( *YES ) +
Dft( *NO ) +
SpcVal(( *NO '0' ) ( *YES '1' )) +
Expr( *YES ) +
PmtCtl( *PMTRQS ) +
Prompt( 'Usage tracking' 13 )
Parm IDXSIZOPT *Char 1 +
Rstd( *YES ) +
Dft( *MAX4GB ) +
SpcVal(( *MAX4GB '0' ) ( *MAX1TB '1' )) +
Expr( *YES ) +
PmtCtl( *PMTRQS ) +
Prompt( 'Index size option' 14 )
Q0001: Qual *Name 10 +
Min( 1 ) +
Expr( *YES )
Qual *NAME 10 +
Dft( *CURLIB ) +
SpcVal(( *CURLIB )) +
Expr( *YES ) +
Prompt( 'Library' )
P0001: PmtCtl Ctl( SEQ ) +
Cond(( *EQ '1' ))
Dep Ctl( &SEQ *NE '1' ) +
Parm(( KEYLEN )) +
NbrTrue( *EQ 0 ) +
MsgId( CPD9501 )
Dep Ctl( &SEQ *EQ '1' ) +
Parm(( KEYLEN )) +
MsgId( CPD9502 )
Panel group
.*-----------------------------------------------------------------------**
.*
.* Compile options:
.*
.* CrtPnlGrp PnlGrp( CBX124H )
.* SrcFile( QPNLSRC )
.* SrcMbr( *PNLGRP )
.*
.*-----------------------------------------------------------------------**
:PNLGRP.
:HELP NAME='CRTUSRIDX'.Create User Index - Help
:P.
The Create User Index (CRTUSRIDX) command creates a user index and
stores it in either the user domain or the system domain.
:P.
A system-domain user index cannot be saved to a release prior to
Version 2 Release 3 Modification 0. A user-domain user index can be
directly manipulated with MI instructions and can also be accessed
using system APIs at all security levels.
:P.
:NT.
If the user index is larger than 4 gigabytes, it cannot be saved to a
release prior to Version 5 Release 2 Modification 0.
:ENT.
:P.
:NT.
For performance reasons, the *USRIDX object is created before checking
to see if it exists in the library specified for the qualified user
index name. If you have an application using this API repeatedly, even
if you are using *NO for the replace parameter, permanent system
addresses will be used.
:ENT.
:P.
:XH3.&MSG(CPX0005,QCPFMSG). CRTUSRIDX
:IMHELP NAME='CRTUSRIDX/ERROR/MESSAGES'.
:EHELP.
:HELP NAME='CRTUSRIDX/ERROR/MESSAGES'.&MSG(CPX0005,QCPFMSG).CRTUSRIDX - Help
:P.
:HP3.*ESCAPE &MSG(CPX0006,QCPFMSG).:EHP3.
:DL COMPACT.
:DT.CPF2143:DD.&MSG(CPF2143,QCPFMSG).
:DT.CPF2144:DD.&MSG(CPF2144,QCPFMSG).
:DT.CPF2283:DD.&MSG(CPF2283,QCPFMSG).
:DT.CPF24B4:DD.&MSG(CPF24B4,QCPFMSG).
:DT.CPF3CF1:DD.&MSG(CPF3CF1,QCPFMSG).
:DT.CPF3CF2:DD.&MSG(CPF3CF2,QCPFMSG).
:DT.CPF3C0A:DD.&MSG(CPF3C0A,QCPFMSG).
:DT.CPF3C0B:DD.&MSG(CPF3C0B,QCPFMSG).
:DT.CPF3C0C:DD.&MSG(CPF3C0C,QCPFMSG).
:DT.CPF3C0D:DD.&MSG(CPF3C0D,QCPFMSG).
:DT.CPF3C0E:DD.&MSG(CPF3C0E,QCPFMSG).
:DT.CPF3C03:DD.&MSG(CPF3C03,QCPFMSG).
:DT.CPD3C01:DD.&MSG(CPD3C01,QCPFMSG).
:DT.CPD3C02:DD.&MSG(CPD3C02,QCPFMSG).
:DT.CPD3C03:DD.&MSG(CPD3C03,QCPFMSG).
:DT.CPD3C05:DD.&MSG(CPD3C05,QCPFMSG).
:DT.CPD3C0A:DD.&MSG(CPD3C0A,QCPFMSG).
:DT.CPD3C0B:DD.&MSG(CPD3C0B,QCPFMSG).
:DT.CPD3C0C:DD.&MSG(CPD3C0C,QCPFMSG).
:DT.CPD3C0D:DD.&MSG(CPD3C0D,QCPFMSG).
:DT.CPD3C0E:DD.&MSG(CPD3C0E,QCPFMSG).
:DT.CPF3C2A:DD.&MSG(CPF3C2A,QCPFMSG).
:DT.CPF3C2B:DD.&MSG(CPF3C2B,QCPFMSG).
:DT.CPF3C2D:DD.&MSG(CPF3C2D,QCPFMSG).
:DT.CPF3C29:DD.&MSG(CPF3C29,QCPFMSG).
:DT.CPF3C34:DD.&MSG(CPF3C34,QCPFMSG).
:DT.CPF3C36:DD.&MSG(CPF3C36,QCPFMSG).
:DT.CPF3C45:DD.&MSG(CPF3C45,QCPFMSG).
:DT.CPF3C49:DD.&MSG(CPF3C49,QCPFMSG).
:DT.CPF3C90:DD.&MSG(CPF3C90,QCPFMSG).
:DT.CPF3C93:DD.&MSG(CPF3C93,QCPFMSG).
:DT.CPF3C95:DD.&MSG(CPF3C95,QCPFMSG).
:DT.CPF8100:DD.All CPF81xx messages could be returned. xx is from 01 to FF.
:DT.CPF9810:DD.&MSG(CPF9810,QCPFMSG).
:DT.CPF9820:DD.&MSG(CPF9820,QCPFMSG).
:DT.CPF9830:DD.&MSG(CPF9830,QCPFMSG).
:DT.CPF9838:DD.&MSG(CPF9838,QCPFMSG).
:DT.CPF9870:DD.&MSG(CPF9870,QCPFMSG).
:DT.CPF9872:DD.&MSG(CPF9872,QCPFMSG).
:EDL.
:EHELP.
:HELP NAME='CRTUSRIDX/USRIDX'.User index (USRIDX) - Help
:XH3.User index (USRIDX)
:P.
Specifies the name and library of the user index being created.
:P.
This is a required parameter.
:P.
:XH3.Library
:P.
Defines the location of the user index.
:P.
The possible values are:
:P.
:PARML.
:PT.:PK DEF.*CURLIB:EPK.
:PD.
The current library for the job is used to locate the user index. If
no current library entry exists in the library list, QGPL is used.
:PT.:PV.library-name:EPV.
:PD.
Specify the library where the user queue is located.
:EPARML.
:EHELP.
:HELP NAME='CRTUSRIDX/EXTATR'.Extended attribute (EXTATR) - Help
:XH3.Extended attribute (EXTATR)
:P.
The extended attribute of the user index. For example, an object type
of *FILE has an extended attribute of PF (physical file), LF (logical
file), DSPF (display file), SAVF (save file), and so on.
:P.
The extended attribute must be a valid *NAME. You can enter this
parameter in uppercase, lowercase, or mixed case. The command
automatically converts it to uppercase.
:P.
The possible values are:
:P.
:PARML.
:PT.:PK DEF.*NONE:EPK.
:PD.
No extended attribute is assigned to the user queue.
:PT.:PV.extended-attribute-name:EPV.
:PD.
Specify a name to be used as the extended attribute for the user queue
object.
:EPARML.
:EHELP.
:HELP NAME='CRTUSRIDX/ENTLENATR'.Entry length attribute (ENTLENATR) - Help
:XH3.Entry length attribute (ENTLENATR)
:P.
Specifies Whether there are fixed-length or variable-length entries in
the user index.
:P.
The possible values are:
:P.
:PARML.
:PT.:PK DEF.*FIXED:EPK.
:PD.
The user index entries have a fixed length.
:PT.:PK.*VARYING:EPK.
:PD.
The user index entries have a variable length.
:EPARML.
:EHELP.
:HELP NAME='CRTUSRIDX/ENTLEN'.Entry length (ENTLEN) - Help
:XH3.Entry length (ENTLEN)
:P.
The length of entries in the index.
:P.
The possible values are:
:P.
:PARML.
:PT.:PK.*SHORT:EPK.
:PD.
Enables a maximum entry length of 120 bytes and a key length from 1
through 120.
:PT.:PK.*MAX:EPK.
:PD.
Enables a maximum entry length of 2000 and a key length from 1 through
2000.
:PT.:PV.entry-length:EPV.
:PD.
The valid values for fixed-length entries are from 1 through 2000.
:EPARML.
:EHELP.
:HELP NAME='CRTUSRIDX/SEQ'.Sequence (SEQ) - Help
:XH3.Sequence (SEQ)
:P.
Whether the inserts to the index are by key.
:P.
The possible values are:
:P.
:PARML.
:PT.:PK DEF.*NONE:EPK.
:PD.
Index entries are not inserted by key.
:PT.:PK.*KEYED:EPK.
:PD.
Index entries are inserted by key.
:EPARML.
:EHELP.
:HELP NAME='CRTUSRIDX/KEYLEN'.Key length (KEYLEN) - Help
:XH3.Key length (KEYLEN)
:P.
The length in bytes of the index entry key from 1 to 2000 if you specify
the user index type as keyed. If you specify that the user index is
not a keyed user index, the value must be 0.
:EHELP.
:HELP NAME='CRTUSRIDX/FORCE'.Force to auxiliary storage (FORCE) - Help
:XH3.Force to auxiliary storage (FORCE)
:P.
Whether the updates to the index are written synchronously to auxiliary
storage on each update to the index.
:P.
The possible values are:
:P.
:PARML.
:PT.:PK DEF.*NO:EPK.
:PD.
Updates to index entries are not immediately forced to auxiliary
storage.
:PT.:PK.*YES:EPK.
:PD.
Updates to index entries are immediately forced to auxiliary
storage.
:EPARML.
:EHELP.
:HELP NAME='CRTUSRIDX/IDXOPZ'.Index optimization (IDXOPZ) - Help
:XH3.Index optimization (IDXOPZ)
:P.
Specifies the type of access in which to optimize the index.
:P.
The possible values are:
:P.
:PARML.
:PT.:PK DEF.*RANDOM:EPK.
:PD.
Optimize for random references.
:PT.:PK.*SEQ:EPK.
:PD.
Optimize for sequential references.
:EPARML.
:EHELP.
:HELP NAME='CRTUSRIDX/AUT'.Authority (AUT) - Help
:XH3.Authority (AUT)
:P.
The authority you give to the users who do not have specific private or
group authority to the user index. Once the user index has been
created, its public authority stays the same when it is moved to
another library or restored from backup media.
:NT.
If the replace parameter is used and a user index exists to be replaced,
this parameter is ignored. All authorities are transferred from the
replaced user index to the new one.
:ENT.
:P.
The possible values are:
:P.
:PARML.
:PT.:PK DEF.*LIBCRTAUT:EPK.
:PD.
The public authority for the user index is taken from the CRTAUT value
for the target library when the object is created. If the CRTAUT value
for the library changes later, that change does not affect user indexes
already created. If the CRTAUT value contains an authorization list
name and that authorization list secures an object, do not delete the
list. If you do, the next time you run this command with the *LIBCRTAUT
parameter, it will fail.
:PT.:PK.*CHANGE:EPK.
:PD.
The user has read, add, update, and delete authority to the user index
and can read the object description.
:PT.:PK.*ALL:EPK.
:PD.
The user can perform all authorized operations on the user index.
:PT.:PK.*USE:EPK.
:PD.
The user can read the object description and the user index' contents
but cannot change them.
:PT.:PK.*EXCLUDE:EPK.
:PD.
The user cannot access the user index in any way.
:PT.:PV.authorization-list-name:EPV.
:PD.
The user index is secured by the specified authorization list, and its
public authority is set to *AUTL. The specified authorization list must
exist on the system when this command is issued. If it does not exist,
the create process fails, and an error message is returned to the
caller.
:EPARML.
:EHELP.
:HELP NAME='CRTUSRIDX/TEXT'.Text 'description' (TEXT) - Help
:XH3.Text 'description' (TEXT)
:P.
Specifies text that briefly describes the user index.
:P.
The possible values are:
:P.
:PARML.
:PT.:PK DEF.*BLANK:EPK.
:PD.
No text is specified.
:PT.:PV.text-'description':EPV.
:PD.
Specify no more than 50 characters, enclosed in apostrophes.
:EPARML.
:EHELP.
:HELP NAME='CRTUSRIDX/REPLACE'.Replace (REPLACE) - Help
:XH3.Replace (REPLACE)
:P.
Specifies whether to replace an existing user index.
:P.
The possible values are:
:P.
:PARML.
:PT.:PK DEF.*NO:EPK.
:PD.
Do not replace an existing user index of the same name and library.
:PT.:PK.*YES:EPK.
:PD.
Replace an existing user index of the same name and library.
:EPARML.
:EHELP.
:HELP NAME='CRTUSRIDX/DOMAIN'.Domain (DOMAIN) - Help
:XH3.Domain (DOMAIN)
:P.
The domain into which the user index should be created.
:P.
The possible values are:
:P.
:PARML.
:PT.:PK DEF.*DEFAULT:EPK.
:PD.
Allows the system to decide into which domain the object should be
created.
:PT.:PK.*SYSTEM:EPK.
:PD.
Creates the user index object into the system domain. The API can
always create a user index into the system domain, regardless of the
security level running. However, if you are running at security level
40 or greater, you must use APIs to access system-domain user index
objects.
:PT.:PK.*USER:EPK.
:PD.
Attempts to create the user index object into the user domain. This is
not always possible. If the library you are creating the user index
into does not appear in the QALWUSRDMN system value, the API cannot
create the user index into the user domain. An error message will be
returned.
:EPARML.
:EHELP.
:HELP NAME='CRTUSRIDX/USGTRK'.Usage tracking (USGTRK) - Help
:XH3.Usage tracking (USGTRK)
:P.
The usage tracking state. Usage tracking provides machine checkpoints
to improve availability of user indexes. If a user index is found to be
a state of partial change, it will be marked as damaged.
:P.
The possible values are:
:P.
:PARML.
:PT.:PK DEF.*NO:EPK.
:PD.
Do not track usage state.
:PT.:PK.*YES:EPK.
:PD.
Track usage state.
:EPARML.
:EHELP.
:HELP NAME='CRTUSRIDX/IDXSIZOPT'.Index size option (IDXSIZOPT) - Help
:XH3.Index size option (IDXSIZOPT)
:P.
The maximum size of the user index.
:P.
The possible values are:
:P.
:PARML.
:PT.:PK DEF.*MAX4GB:EPK.
:PD.
The maximum size of the user index is 4 gigabytes.
:PT.:PK.*MAX1TB:EPK.
:PD.
The maximum size of the user index is 1 terabyte.
:EPARML.
:EHELP.
:EPNLGRP.
Thanks to Carsten Flensburg writing for
Club Tech iSeries Programming Tips Newsletter
|