QUSCRTUI - Create User Index

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