_RSLOBJ() and _RSLOBJ2()--Resolve to an IBM i Object for IBM PASE for i

Syntax

 #include <as400_protos.h>

 int _RSLOBJ(ILEpointer       *sysptr,
             const char       *path,
             char             *objtype);

 int _RSLOBJ2(ILEpointer      *sysptr,
              unsigned short  type_subtype,  
              const char      *objname,
              const char      *libname);

  Default Public Authority: *USE

  Library: Standard C Library (libc.a)

  Threadsafe: Yes

Note: These functions can only be used in an IBM^® i PASE program. See the IBM PASE for i topic collection for more information about creating IBM PASE for i programs.

The _RSLOBJ() and _RSLOBJ2() functions resolve to an IBM i object. They accept symbolic information that identifies the object and return a 16-byte tagged system pointer to the specified object.

Parameters

sysptr

(Output) Pointer to the IBM i object. sysptr is the address of a 16-byte aligned buffer allocated by the caller and used to return a system pointer to the IBM i object.

path

(Input) Pointer to an Integrated File System path name that locates the IBM i object. path is the address of a null-terminated string in the IBM PASE for i CCSID that contains a path name for the IBM i object.

objtype

(Output) Pointer to the returned IBM i object type. objtype is the address of a buffer allocated by the caller and used to return a null-terminated string in the IBM PASE for i CCSID that identifies the IBM i object type. If objtype is a null pointer, no IBM i object type is returned. When objtype is not null, the caller must provide a buffer of length RSLOBJ_OBJTYPE_MAXLEN (11) to avoid errors.

type_subtype

(Input) Object type and subtype. type_subtype specifies the MI object type and MI object subtype of the IBM i object. Header file <as400_types.h> declares these constants for type and subtype values:

RSLOBJ_TS_PGM
(0x0201)

Specifies the MI type and subtype for an IBM i program (object type *PGM).

RSLOBJ_TS_SRVPGM
(0x0203)

Specifies the MI type and subtype for an IBM i service program (object type *SRVPGM).

objname

(Input) Pointer to the name of the IBM i object. objname is the address of a null-terminated string in the IBM PASE for i CCSID that contains the name of the IBM i object.

libname

(Input) Pointer to the name of the IBM i library that contains the object. libname is the address of a null-terminated string in the IBM PASE for i CCSID that contains the name of an IBM i library. Specifying a null pointer or a pointer to a null string is the same as specifying "*LIBL", which searches the thread library list.

Authorities

Object Referred to

Authority
Required

Every directory in the Integrated File System path to the IBM i object

IBM i library that contains the object

Return Value

The function result is zero if the IBM i object was found and a system pointer was returned in the sysptr argument. A function result of -1 indicates an error that is further qualified by an errno value.

Error Conditions

Memory errors may be reported with an IBM i exception message that the system converts to an IBM PASE for i signal (not return code and errno values). See IBM PASE for i Signal Handling for information about handling IBM i exceptions.

At least these errno values can be returned, with other values also possible (such as IBM i-unique ILE errno EAPAR):

[EACCES]

Not authorized to a library or directory needed to resolve to the IBM i object.

[EBUSY]

A library or directory needed to resolve to the IBM i object is currently in use (locked).

[EFAULT]

A memory fault occurred attempting to reference an argument.

[EINVAL]

An invalid argument value was specified.

[EINTER]

An signal interrupted the operation.

[ENAMETOOLONG]

Some component of the specified path is too long, or the entire path exceeds the system limit, or the objname or libname string is longer than 30 characters.

[ENOENT]

The specified IBM i object was not found.

[ENOTDIR]

A qualifier part of the path is not a directory.

[ELOOP]

Too many levels of symbolic links.

Usage Notes

For _RSLOBJ, alphabetic case is either ignored or honored depending on the attributes of the file system that contains the path. Alphabetic case is always honored by _RSLOBJ2, so the objname and libname strings must be uppercase.

Related Information

API introduced: V5R2

[ Back to top | IBM PASE for i APIs | APIs by category ]