| w w w . P r o v a t o S y s . c o m |
| M i c h a e l C a t a l a n i |
| 9 0 1 . 5 8 1 . 8 7 9 1 |
|
|
|
The Object_s service program contains functions that utilize the QUSROBJD api. This api allows your program to retrieve information about an object on your system, such as the object owner, object size, save and restore information, etc.
Function Example
Let's say we want to retrieve the owner of an
object. By utilizing the functions inside this service program, we can code the following in our rpg program:
Owner = Object_RetrieveObjectOwner( ObjectName : ObjectLibrary : ObjectType);
One of the nice things that come from using a service program to access object data (via the QUSROBJD api) is that our program doesn't have to include the code in which to access the api itself. The code for api's can clutter up a program. By creating functions and bundling them into a service program, we create re-usable code that eliminates the clutter inside our programs, and which is self-documenting.
Program Example
Here's a quick program example which utilizes the service program to display
some of the information available about an object. I named this program ObjectR.
The following screen shows what the example program looks like:
The following is the rpg source for the ObjectR program:
h dftactgrp( *no ) Option( *srcstmt : *nodebugio ) BndDir( 'CF' )
FObjectd CF E WORKSTN
/copy *libl/qrpglesrc,object_p
/free
dow NOT *inlr;
exfmt Screen01;
if *in03;
*inlr = *on;
else;
if Object_ObjectExists( Object : Library : Type );
Exist = 'Yes';
else;
Exist = 'No';
endif;
ObjLib = object_RetrieveObjectLibrary( Object : Library : Type );
Owner = object_RetrieveObjectOwner( Object : Library : Type );
Desc = object_RetrieveObjectDescription( Object : Library : Type );
Asp = object_RetrieveObjectAsp( Object : Library : Type );
Size = object_RetrieveObjectSize( Object : Library : Type ) *
object_RetrieveObjectMultiplier( Object : Library : Type );
endif;
enddo;
The following is the DDS for the ObjectD display file which is used by the ObjectR program:
A*%%TS SD 20090216 103647 QPGMR REL-V6R1M0 5761-WDS
A*%%EC
A DSPSIZ(24 80 *DS3)
A CF03(03)
A R SCREEN01
A*%%TS SD 20090216 103647 QPGMR REL-V6R1M0 5761-WDS
A 5 2'Object Name...:'
A COLOR(BLU)
A 6 2'Object Library:'
A COLOR(BLU)
A 7 2'Object Type...:'
A COLOR(BLU)
A OBJECT 10A B 5 18COLOR(WHT)
A LIBRARY 10A B 6 18COLOR(WHT)
A TYPE 10A B 7 18COLOR(WHT)
A 23 2'F3-Exit'
A COLOR(WHT)
A 1 2DATE
A EDTCDE(Y)
A COLOR(PNK)
A 2 2TIME
A COLOR(PNK)
A 1 70USER
A COLOR(PNK)
A 1 28'Object Information'
A COLOR(BLU)
A 9 2'Object Exists.:'
A COLOR(BLU)
A 11 2'Owner.........:'
A COLOR(BLU)
A 10 2'Library.......:'
A COLOR(BLU)
A 6 30'(You may specify *LIBL)'
A COLOR(PNK)
A 12 2'Asp Location..:'
A COLOR(BLU)
A 13 2'Object Size...:'
A COLOR(BLU)
A 14 2'Description...:'
A COLOR(BLU)
A EXIST 3A O 9 19
A OBJLIB 10A O 10 19
A OWNER 10A O 11 19
A ASP 3Y 0O 12 19EDTCDE(Z)
A SIZE 12Y 0O 13 19EDTCDE(2)
A DESC 50A O 14 19
The Object_s Service Program
Bundled with this service program are several functions.
It only takes a few minutes to create a new function to return any of the data
that the QUSROBJD api returns in it's OBJD0400 format.
Note that each of the functions start with "Object_" . This is a naming standard that says the service program name where these functions are located is Object_s. Also, the prototypes are located in Object_p. By following this naming convention, I can quickly locate the source and prototype for any function I find in a program.
Here's the functions that are already created in the Object_s service program:
| Object_GetObjectData |
This function is a wrapper for the QUSROBJD api. The function returns an indicator to determine if the object exists or not, and passes the OBJD0400 data structure format back if the object is found. |
| Object_ObjectExists |
Returns *on if the object is found, or *off if it is not found. |
| Object_RetrieveObjectLibrary |
Returns the library in which the object was found. If you pass *LIBL for the library, then this function will return the library in which the object was located. |
| Object_RetrieveObjectOwner |
Returns the object owner |
| Object_RetrieveObjectSize |
Returns the object size |
| Object_RetrieveObjectMultiplier |
Returns the object size multiplier. You must multiply this value by the size in order to get the true size of an object. This value is normally 1, but for extremely large objects it can be any value. |
|
Object_RetrieveObjectDescription |
Returns the text description of the object |
| Object_RetrieveObjectAsp | Returns the asp number that the object in located in |
You can also create additional functions to return any data for an object that is returned in the OBJD0400 data structure in a matter of minutes. The procedure for doing this is located in the top comment section of the service program source.
The following code sections should be copied into the appropriate file and members. I use a library named "CF", for "custom functions", for all of my service programs which contain functions which can be accessed across the system. So within my CF library, I have a source file QRPGLESRC and QSRVSRC. The following members below then need to be created in their respective files in the library.
Object_p Prototype Source
The following source code should be placed in a source file member
called Object_p. These are the prototypes for the Service
Program.
/copy *libl/qrpglesrc,OBJD0400
dObject_GetObjectData...
d pr n
d ObjectName 10a const
d LibraryName 10a const
d ObjectType 10a const
d ObjectData like(OBJD0400) options(*nopass)
d Object_ObjectExists...
d pr n
d ObjectName 10a const
d LibraryName 10a const
d ObjectType 10a const
d Object_RetrieveObjectLibrary...
d pr like(OBJD0400.ReturnLibrary)
d ObjectName 10a const
d LibraryName 10a const
d ObjectType 10a const
d Object_RetrieveObjectDescription...
d pr like(OBJD0400.Text)
d ObjectName 10a const
d LibraryName 10a const
d ObjectType 10a const
d Object_RetrieveObjectAsp...
d pr like(OBJD0400.Asp)
d ObjectName 10a const
d LibraryName 10a const
d ObjectType 10a const
d Object_RetrieveObjectSize...
d pr like(OBJD0400.Size)
d ObjectName 10a const
d LibraryName 10a const
d ObjectType 10a const
d Object_RetrieveObjectMultiplier...
d pr like(OBJD0400.SizeMultiplier)
d ObjectName 10a const
d LibraryName 10a const
d ObjectType 10a const
dObject_RetrieveObjectOwner...
d pr like(objd0400.Owner)
d
d Name 10a const
d Library 10a const
d Type 10a const
/if defined(OBJD0400)
/eof
/endif
/define OBJD0400
d OBJD0400 ds inz qualified
d
d BytesReturned 10i 0
d BytesAvailable...
d 10i 0
d Name 10a
d Library 10a
d Type 10a
d ReturnLibrary 10a
d Asp 10i 0
d Owner 10a
d Domain 2a
d Created 13a
d Changed 13a
d Attribute 10
d Text 50
d SourceFile 10
d SourceLibrary 10
d SourceMember 10
d SourceChangeDate...
d 13
d SourceSaveDate...
d 13
d SourceRestoreDate...
d 13
d CreateUser 10
d CreateSystem 8
d RestoreDate 7
d SaveSize 10i 0
d SaveSequence 10i 0
d Storage 10
d SaveCommand 10
d SaveVolumeID 71
d SaveDevice 10
d SaveFile 10
d SaveLibrary 10
d SaveLabel 17
d SaveLevel 9
d Compiler 16
d Level 8
d UserChange 1
d LicenseProgram...
d 16
d PTF 10
d Apar 10
d UseDate 7
d UsageInfo 1
d UseDays 10i 0
d Size 10i 0
d SizeMultiplier...
d 10i 0
d CPRStatus 1
d AllowChange 1
d ChangeProgram 1
d UserAttribute 10
d OverFlowAsp 1
d SaveActDate 7
d SaveActTime 6
d AuditValue 10
d ProgramGroup 10
ApiError Data Structure
The following source should be copied into a member called APIERROR. This is the
error data structure used for most of the IBM api's.
/if defined(ApiError)
/eof
/endif
/define ApiError
D ApiError Ds inz qualified
D Bytes 10i 0 inz( %Size( ApiError ))
D BytesAvail 10i 0 inz
D ErrorID 7a inz
D Reserved 1a inz(x'00')
D MessageData 128a inz
Object_s Binder Source
The following source should be copied into a member called Object_s
in QSRVSRC. This is the binder language for the service program functions.
STRPGMEXP PGMLVL(*CURRENT)
EXPORT SYMBOL(Object_ObjectExists)
EXPORT SYMBOL(Object_GetObjectData)
EXPORT SYMBOL(Object_RetrieveObjectLibrary)
EXPORT SYMBOL(Object_RetrieveObjectDescription)
EXPORT SYMBOL(Object_RetrieveObjectAsp)
EXPORT SYMBOL(Object_RetrieveObjectSize)
EXPORT SYMBOL(Object_RetrieveObjectMultiplier)
EXPORT SYMBOL(Object_RetrieveObjectOwner)
ENDPGMEXP
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* @copyrite 2009 Michael Catalani
*
* Service Program - Object_s
*
* This service program contains functions and procedures related
* to IBM's QUSROBJD api.
*
* FUNCTION NAME DESCRIPTION
* Object_GetObjectData Wrapper for the QUSROBJD api
* Object_ObjectExists Determines if the object exists
* Object_RetrieveObjectLibrary Returns library wer object was found
* Object_RetrieveObjectSize Returns the object size
* Object_RetrieveObjectMultiplier Returns the object size multiplier
* Object_RetrieveObjectDescrption Returns text of the object description
* Object_RetrieveObjectAsp Returns the asp# of the object
* Object_RetrieveObjectOwner Returns the object owner
*
* Object_(xxxxx) You can create a new function to
* return any of the data located in the
* OBJD0400 data structure by copying the
* source of OBJECT_RetrieveObjectAsp.
* The steps needed to create a new
* function are:
*
* In the Object_s source member
* 1. Copy the OBJECT_RetrieveObjectAsp
* function code and give it a new
* function name.
* 2. Change the returned field on the
* procedure interface to the field
* you want returned
* 3. Change the return opcode to return
* the correct field name
*
* In the Object_p source member
* 4. Create a prototype for the new
* function. (Copy the prototype for
* Object_RetrieveObjectAsp and change
* the returned field name.
*
* In the QSRVSRC, Object_s member
* 5. Add the new function to the binder
* source
*
* 6. Recompile the service program
*
* ApiError - This data structure is located in a member called ApiError.
* for IBM api's.
*
* OBJD0400 - This is the data structure format used in the QUSROBJD api.
* a member called OBJD0400.
*
* NOTE - If you want to return all of the fields from the QUSROBJD api,
* instead of one field at a time that each function returns, use the
* Object_GetObjectData function. This function returns *on / *off if the
* object was found, and passes back the entire OBJD0400 data structure
* as a 4th parameter.
*
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
h nomain
* Prototypes
/copy *libl/qrpglesrc,Object_p
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
*
* Function-Object_GetObjectData
* This function returns whether or not the object was found, and
* the OBJD0400 data structure back as a parameter. This function
* is a wrapper for the QUSROBJD api.
*
* Input Parms - Object Name 10a
* Object Library 10a (you may specifiy *LIBL)
* Object Type 10a
*
* Output Parms - OBJD0400 Data Structure
*
* Returns - Indicator (*on if object found, *off if object is not found)
*
* Suggested Code Usage
*
* if Object_GetObjectData( Name : Library : Type : OBJD0D0400 );
* ObjectOwner = OBJD0400.Owner;
* endif;
*
* Please Note - Although the OBJD0400 parameter is optional, you should
* always pass it. If you dont specify the parameter, then all the function
* does is dtermine whether or not the object was found, in which case you
* should use the Object_ObjectExists function.
*
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
pObject_GetObjectData...
p b export
dObject_GetObjectData...
d pi n
d
d Name 10a const
d Library 10a const
d Type 10a const
d ObjectData like(OBJD0400) options(*nopass)
/copy *libl/qrpglesrc,ApiError
d QUSROBJD pr ExtPgm( 'QUSROBJD' )
d Receiver 32767a Options( *VarSize )
d ReceiverLen 10i 0 Const
d FormatName 8a Const
d ObjectLibName 20a Const
d TypeName 10a Const
d ErrorField 32767a Options( *VarSize )
/free
clear objd0400;
QUSROBJD( OBJD0400
: %Size( OBJD0400 )
: 'OBJD0400'
: Name + Library
: Type
: ApiError
);
If ApiError.ErrorID = *blanks;
return *on ;
else;
return *off;
endif;
/end-free
p e
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
*
* Function - Object_ObjectExists
* This function determines whether or not the object exists
*
* Input Parms - Object Name 10a
* Object Library 10a (you may specifiy *LIBL)
* Object Type 10a
*
* Returns - Indicator (*on if object found, *off if object is not found)
*
* Suggested Code Usage
*
* ObjectFound = Object_Exists( ObjectName : ObjectLibrary : ObjectType );
*
*
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
pObject_ObjectExists...
p b export
dObject_ObjectExists...
d pi n
d
d Name 10a const
d Library 10a const
d Type 10a const
/free
If Object_GetObjectData( name : Library : Type );
return *on ;
else;
return *off;
endif;
/end-free
p e
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
*
* Function - Object_RetrieveObjectLibrary
* Returns the library the object was located in. (This value w
* same as the library passed to the function unless *LIBL was s
*
*
* Input Parms - Object Name 10a
* Object Library 10a (you may specifiy *LIBL)
* Object Type 10a
*
* Returns - Library Name Where Object Was Located. 10a
*
* Suggested Code Usage
*
* LibraryName = Object_RetrieveObjectLibrary( Name : '*LIBL' : Type );
*
*
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
pObject_RetrieveObjectLibrary...
p b export
dObject_RetrieveObjectLibrary...
d pi like(objd0400.ReturnLibrary)
d
d Name 10a const
d Library 10a const
d Type 10a const
/free
Object_GetObjectData( name : Library : Type : objd0400 );
return objd0400.ReturnLibrary;
/end-free
p e
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
*
* Function - Object_RetrieveObjectDescription
* Retrieves the objects text description
*
* Input Parms - Object Name 10a
* Object Library 10a (you may specifiy *LIBL)
* Object Type 10a
*
* Returns - Objects Text Description (50a)
*
* Suggested Code Usage
*
* Description = Object_RetrieveObjectDescription( Name : Library : Type);
*
*
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
pObject_RetrieveObjectDescription...
p b export
dObject_RetrieveObjectDescription...
d pi like(objd0400.Text)
d
d Name 10a const
d Library 10a const
d Type 10a const
/free
Object_GetObjectData( Name : Library : Type : OBJD0400 );
return objd0400.Text;
/end-free
p e
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
*
* Function - Object_RetrieveObjectAsp
* Retrieves the objects Asp#
*
* Input Parms - Object Name 10a
* Object Library 10a (you may specifiy *LIBL)
* Object Type 10a
*
* Returns - Objects Text Description (10i)
*
* Suggested Code Usage
*
* Asp# = Object_RetrieveObjectAsp( Name : Library : Type );
*
*
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
pObject_RetrieveObjectAsp...
p b export
dObject_RetrieveObjectAsp...
d pi like(objd0400.Asp)
d
d Name 10a const
d Library 10a const
d Type 10a const
/free
Object_GetObjectData( Name : Library : Type : OBJD0400 );
return objd0400.Asp;
/end-free
p e
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
*
* Function - Object_RetrieveObjectSize
* Retrieves the objects size (Note - this amount must be multi
* by the size multiplier field)
*
* Input Parms - Object Name 10a
* Object Library 10a (you may specifiy *LIBL)
* Object Type 10a
*
* Returns - Object Size (10i)
*
* Suggested Code Usage
*
* Size = Object_RetrieveObjectSize( Name : Library : Type ) *
* Object_RetrieveObjectMultiplier( Name : Library : Type );
*
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
pObject_RetrieveObjectSize...
p b export
dObject_RetrieveObjectSize...
d pi like(objd0400.Size)
d
d Name 10a const
d Library 10a const
d Type 10a const
/free
Object_GetObjectData( Name : Library : Type : OBJD0400 );
return objd0400.Size;
/end-free
p e
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
*
* Function - Object_RetrieveObjectMultiplier
* Retrieves the objects size multiplier
*
*
* Input Parms - Object Name 10a
* Object Library 10a (you may specifiy *LIBL)
* Object Type 10a
*
* Returns - Object Multiplier (10i)
*
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
pObject_RetrieveObjectMultiplier...
p b export
dObject_RetrieveObjectMultiplier...
d pi like(objd0400.SizeMultiplier)
d
d Name 10a const
d Library 10a const
d Type 10a const
/free
Object_GetObjectData( Name : Library : Type : OBJD0400 );
return objd0400.SizeMultiplier;
/end-free
p e
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
*
* Function - Object_RetrieveObjectOwner
* Retrieves the Owner Of The Object
*
*
* Input Parms - Object Name 10a
* Object Library 10a (you may specifiy *LIBL)
* Object Type 10a
*
* Returns - Object Owner (10a)
*
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
pObject_RetrieveObjectOwner...
p b export
dObject_RetrieveObjectOwner...
d pi like(objd0400.Owner)
d
d Name 10a const
d Library 10a const
d Type 10a const
/free
Object_GetObjectData( Name : Library : Type : OBJD0400 );
return objd0400.Owner;
/end-free
p e
Once the members have been copied, we need to create the module and service program. I will show the following commands using the CF library name, but you need to substitute the library you are using if it is different.
CRTRPGMOD MODULE(CF/OBJECT_S) SRCFILE(CF/QRPGLESRC) DBGVIEW(*ALL)
CRTSRVPGM SRVPGM(CF/OBJECT_S) SRCFILE(CF/QSRVSRC)
Now I need to add the service program to my binding directory. If I didn't have a binding directory set up yet, I would do so by issuing the command:
CRTBNDDIR BNDDIR(CF/CF)
The above command would then create a binding directory in my CF library.
Next, I would need to add this service program to the binding directory:
ADDBNDDIRE BNDDIR(CF/CF) OBJ((CF/OBJECT_S))
You should now be all set to begin using these functions. There are only 2 steps to take in order to use these functions in your program:
1) Make sure you specify the binding directory in your control (H) spec:
ie: H bnddir( 'CF' )
2) Use the /copy directive in order to copy in the prototypes for the functions:
ie : /copy *libl / qrpglesrcl, Object_p
End of document