Lovelady's API Samples

Back to lovelady.com Music pages Unix sources RPG API Samples The TAO of Programming Fortune cookies Picture gallery

crtusrspc

// Create a user space, make it extendable, and return pointer


// When desaling with IBM APIs, it is often desireable (and sometimes
// required) to place the output into a user space. Properly utilized,
// this can free RPG programs of limitations such as 64K maximum data
// structure/field size, et cetera.
//
// The API for creation of User Space has a couple of shortcomings.
// First, it does not return a pointer to the created space. Secondly,
// the created space is of a fixed size and not extendable, which
// promotes the overallocation of space, or invites exceptions when
// user spaces are not created "large enough." But IBM provides the
// QUSCUSAT to change User Space attributes, including the bit that
// controls whether a user space is extendable.
//
// This program creates the user space and makes it extendable, allowing
// for efficient use of space.
//
// If the User Space already exists, then it will NOT be deleted nor
// replaced. Instead, the existing object is used.
//
// Upon successful completion, a pointer to the user space is returned.

H OPTION(*NOSHOWCPY:*NOEXPDDS:*NODEBUGIO:*SRCSTMT)
H DATFMT(*ISO) TIMFMT(*ISO)
H CVTOPT(*VARCHAR:*DATETIME)
H BndDir('QC2LE')
H NOMAIN

//******************************************************************
// ---Log-------------------------------------Author--------Date-- *
// Original version Lovelady 26-Jan-06 *
// ---End of log-------------------------------------------------- *
//******************************************************************



D* Structure for Error Code Parameter

D aceUSEC DS Qualified
D QUSBPRV 10I 0 Inz(%Size(aceUSEC)) Bytes provided
D QUSBAVL 10I 0 Bytes available
D QUSEI 7 Exception ID
D reserved 1
D QUSED01 1024 Exception data



//******************************************************************
// Create User Space
//******************************************************************
D createUserSpace...
D PR * ExtProc('createUserSpace')
D UsrSpcName 20 Value
D UsrSpcDescr 50 Value
D ExtAttr 10 Value Options(*NoPass)
D USEC LikeDS(aceUSEC) Options(*NoPass)



//******************************************************************
// Delete User Space
//******************************************************************
D DeleteUserSpace...
D PR ExtPgm('QUSDLTUS')
D SpaceName 20 Const
D ErrorParm Like(aceUSEC)



//******************************************************************
// Retrieve Pointer to a User Space object
//******************************************************************
D rtvPtrUserSpace...
D PR ExtPgm('QUSPTRUS')
D SavFSpace 20 Const
D ReturnPtr *
D ErrorParm Like(aceUSEC)


//******************************************************************
// Create a user space
//******************************************************************
D IBMCrtUsrSpc...
D PR ExtPgm('QUSCRTUS')
D SavFSpace 20 Const
D Attr 10 Const
D InlSize 10I 0 Const
D InlValue 1 Const
D Authority 10 Const
D TextDescr 50 Const
D Replace 10 Const
D ErrorParm Like(aceUSEC)


//******************************************************************
// IBM API QUSCUSAT will change a user space's attributes. We use
// this to make a user space extendable
//******************************************************************
D chgUserSpaceAttr...
D PR ExtPgm('QUSCUSAT')
D RtnLib 10
D SpaceName 20 Const
D AttrList 32767 Const Options(*VarSize)
D ErrorParm Like(aceUSEC)



////////////////////////////////////////////////////////////////////
// Create a user space
//
// This routine will create a user space, or will modify an existing
// one to be extendable. This procedure returns a pointer to the
// user space.
//
// Parameters: (First two are required)
// > UserSpcName (20 bytes: first 10 are object; next 10 are lib)
// > Text description (50 bytes)
// > Extended attribute (see in DSPOBJD, et cetera)
// > Return error structure
////////////////////////////////////////////////////////////////////

P createUserSpace...
P B Export
D createUserSpace...
D PI *
D UsrSpcName 20 Value
D UsrSpcDescr 50 Value
D ExtAttr 10 Value Options(*NoPass)
D UserUSEC LikeDS(aceUSEC) Options(*NoPass)

D UsrSpcExtAttr S 10 Inz('"WorkArea"')
D SpcPointer S *
D ReturnLib S 10
D myUSEC DS LikeDS(aceUSEC) Inz



D* Structure to change the USRSPC attr to extendable
D ChangeAttrs DS
* Description field-by-field
* Number_Attrs = Number of attributes (1)
* 1-element array of attribute definitions as follows:
* Attr_Key1 = Identify attribute to change (3=Extendable attr.)
* Attr_Siz1 = Length of the attribute itself (1)
* Attr_Dta1 = New value for this attribute ('1'="yes")
D Number_Attrs 10I 0 Inz(1)
D Attr_Key1 10I 0 Inz(3)
D Attr_Siz1 10I 0 Inz(1)
D Attr_Dta1 1 Inz('1')

/Free
//******************************************************************
// Because we don't know how big the user spaces used by this pgm *
// need to be, we'll create them small and make them extendable. *
// API QUSCRTUS will create the User Space objects and QUSCUSAT *
// will allow us to change attributes to extendable. *
//******************************************************************

myUSEC.QUSBPRV = %Size(myUSEC) ;

If %Parms >= 3 And %Addr(ExtAttr) <> *Null And ExtAttr <> *Blanks ;
UsrSpcExtAttr = ExtAttr ;
EndIF ;

// Attempt to obtain pointer to requested space. If successful,
// we do not need to create a new space (it already exists).
rtvPtrUserSpace(UsrSpcName : SpcPointer : myUSEC) ;
If (myUSEC.QUSBAVL > *Zero) ; // Gotta make a new one
myUSEC.QUSBAVL = *Zero ;
// Create our user space
IBMCrtUsrSpc(UsrSpcName // User space name
: UsrSpcExtAttr // Extended Attribute
: 1024 // INLSIZ(1024)
: x'00' // INLVAL(X'00')
: '*USE' // AUT(*USE)
: UsrSpcDescr // User space description
: '*YES' // REPLACE(*YES)
: myUSEC
) ;
If (myUSEC.QUSBAVL = *Zero) ; // No error
rtvPtrUserSpace(UsrSpcName // Retrieve pointer to space
: SpcPointer
: myUSEC) ;
// Change user space to be extendable
chgUserSpaceAttr(ReturnLib // Set to extendable
: UsrSpcName
: ChangeAttrs
: myUSEC) ;
EndIF ;
EndIf ;
If %Parms >= 4 ; // Caller requested error structure
UserUSEC = myUSEC ; // so pass it along
EndIF ;

If (myUSEC.QUSBAVL > *Zero) ; // Error occurred
Return *NULL ;
Else ;
Return SpcPointer ; // No error. Return the pointer
EndIF ;
/End-free

P createUserSpace...
P E


This page is devoted to examples that demonstrate how to call certain IBM APIs from ILE-RPG on iSeries (System i, AS/400 or whatever its name is this week). Generally, any programs and/or snippets placed here are not intended to be plug-in solutions for whatever current problem, but are rather intended as a how-to by example. My hope is that some will benefit from these and will be able to roll their own improvements.

List of examples:

crtusrspcCreate a user space, make it extendable, and return pointer
RTVJOBINFDemonstrates use of QUSRJOBI to retrieve long library list. Format JOBI0750 is used.
qjobDemonstrates use of QUSLJOB with the JOBL0200 format (to return select list of fields)




counter visitors since 8-July-2008

Quote of the day:"

"We can't all be heroes, because somebody has to sit on the curb and clap as they go by."
    — Will Rogers


Last updated: Dec 31, 1969 at 07:00PM America/New_York
image
There's no place like home
image
Write to me
Make a request