TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Apex Shell Object Types


Standard Operations

This chapter describes the object types and operations available in Apex Shell.

There are several operations that are standard for all object types.

Procedures

.operations

Displays the names of the functions and procedures available for the type. For example, the following displays all procedure's and functions for string_set.

.show

Displays an image of the object.

.destroy

Deletes the object, "undeclares" the object name, and frees up memory used by the object.

Functions

.name

Returns the name or handle of an object if that notion is meaningful for that particular object type. If not, the null string is returned.

.type_name

Returns the name of the type.

.fail

Returns 1 if an error condition has been set for the object.

.error

Returns the string image of the latest condition set for the object.

Iteration

Some types support iteration. The iteration operations are:

iterate (procedure), done (function), current (function), next (procedure)

For example (where m1 is a string_map):

Assignment

Some object types support assignment directly from one object to another. For example:

assigns an object a2 to object a1. The argument a2 must be the same object type as a1.


Object Types

The following Object Types are discussed in this chapter:

Tokens are contiguous sequences of nonspace characters or a sequence of charactes contained within a pair of double quotes. Nested double quotes (a double quote within a quoted token) should be doubled.

byte_string

A byte_string is a flexible array of bytes. The lower bound is zero.

If no arguments are given, a newly declared array has length zero. The -size option allows one to specify the number of slots to initially allocate in the array. If -address is given, this byte string aliases the <address> given. The length of this one will be equal to string length of the other. If -alias is given, this byte string aliases the <address> given and this one has a length of the <count> given

Procedures

append <string>

append a string value

append_byte <integer>

append a byte

append_htonl

append a long using Host_To_Net conversion

append_long

append a long value

delete <index> [<count>]

delete <count> bytes starting at <index>
the default count is 1

ensure_storage <count>

ensure array has space for <count> bytes

extend <count>

extend the length of array by <count>

insert <index> <string>

insert the given <value> at position <index>

insert_bytes <index> <address> <length>

insert <length> bytes which start at <address> into array at position <index>

make_empty

make the array have 0 length

set <index> <string>

replace byte(s) starting at <index> with <string>

set_byte <index> <integer>

replace byte at <index> with byte <integer>

set_bytes <index> <address> <length>

replace <length> bytes starting at <index> with those from <address>

Functions

byte <index>

get the byte at <index> as an integer string

char <index>

get the character value at <index>

get_long <index>

get the 4 bytes at <index> as an integer string

get_ntohl <index>

get the 4 bytes at <index> and do Net_To_Host

last

get value of the last index position

length

get the length of the array

size

get the storage length of the array

start

get the address of the start byte of the array

substring <start> <count>

get a substring starting at <start> for <count> characters

value

get a copy as a string

Examples

configuration

A configuration is an interface to an apex configuration file

Functions

view_names

full pathnames of the views in the configuration

view_of_subsystem <subsystem>

canonical pathname of the view in the indicated subsystem

connection

This object type provides an interface to Unix sockets. Both send and receive connections are supported.

The forms that name a host and port create send connections. -persistent is used when connecting to an Apex session. A register request will be sent and the connection can be used to send multiple requests using the request object type described later.

Procedures

close

close the connection

job_start <job_line> [<cmd_line>]

register with the apex jobs window the connection should be to an Apex session

register <server_name> [<cmd_info> [<cmd_line>]]

register as an Apex server

Functions

accept

do an accept on the socket
if successful, returns a new connection object

host

host number from the socket in decimal

image

Host_Number:Port_Number

is_null

is the connection object null

kind

integer kind of the connection

port

port number from the socket

read <var_name> <count>

read bytes into the variable given
returns count of the bytes read

read_bytes <address> <count>

read bytes from the connection.
returns count of the bytes read

socket

socket number

write <string>

write a string into the connection
returns count of the bytes written

write_bytes <address> <count>

write bytes into the connection
returns count of the bytes written

Example - having a shell script register as a job or server with Apex

Example - writing to a socket at the byte level

directory

A directory is an interface to a UNIX directory object.

Functions

subsystem_name

enclosing subsystem full pathname

view_name

enclosing view full pathname

owner_id

user id of the object's owner

owner_name

user name of the object's owner

group_id

group id of the object

group_name

group name of the object

size

byte size

modify_time

time of last modification as an integer

is_link

is the object a link

link_value

value of the link, if object is a link

link_target

full pathname of the value of the link, if object is a link

access_image

rwx, etc. image

mode_value

octal value of the stat mode

directory_entries

simple names of the items in the directory

Procedures

delete

filesystem delete of the object

rename <new_name>

filesystem rename of the object

element

An element is an interface to an object of a subsystem

Functions

first_version_number

first version number of the element

last_version_number

last version number of the element

version_count

count of the number of versions

subsystem_name

subsystem name from the element handle

element_name

element name from the element handle

history_name

history name from the element handle

version <version_number>

version object for the given version number

file

A file is an interface to a UNIX file object. If the object is within a view, then CMVC information can be obtained.

If the -create option is given, the file will be created. To perform filesystem operations on Apex objects, use the appropriate subcommands of the Apex executable.

Many operations on this type are performed on the file name itself; the file itself does not necessarily have to exist.

Functions

name

returns the full, canonical pathname of the file

subsystem_name

enclosing subsystem full pathname

view_name

enclosing view full pathname

code_file_name

filename of the corresponding (object) code file

status

CMVC status of this object

element_name

view_relative name of this object

history_name

history name of this object

version_number

this object's version number

latest_status

CMVC status of the latest version of this object

latest_version_number

version number of the latest version of this object

version [<number>]

returns a "version" object for this object

owner_id

user id of the object's owner

owner_name

user name of the object's owner

group_id

group id of the object

group_name

group name of the object

size

byte size of the object

modify_time

time of last modification as an integer
the result can be interpreted using the time_value object

is_link

is the object a link

link_value

value of the link, if object is a link

link_target

full pathname of the value of the link, if object is a link

access_image

rwx, etc image

mode_value

octal value of the stat mode

attribute <attribute_name>

attribute value of the specified user-defined attribute for this object

is_ada

is the file an ada file

is_c

is the file a c file

is_c_or_cpp

is the file a c or C++ file

is_controlled

is the file a controlled file

is_cpp

is the file a C++ file

is_h

is the file a header file

is_h_c_or_cpp

is the file a header, c, or C++ file

is_h_or_cpp

is the file a header or C++ file

other_part

ada, c, or C++ Other_Part filename

editor_name

editor associated with this kind of object

object_kind

value of the base object_kind of the file

open [-locked | -shared] [-wait <number>] [-read | -write | -update]

opens the file denoted by this object. Returns a file_descriptor object. The default open mode is for writing. The default is to open the file unlocked unless the -locked or -shared option is given.

open_stream

like the open operator but returns a file_stream object

Procedures

delete

filesystem delete of the object

rename <new_name>

filesystem rename of the object

Status results will be one of the values:

make_executable [<category>]

make the file executable

make_nonexecutable [<category>]

make the file nonexecutable

make_read_only [<category>]

make the file read only

make_writable [<category>]

make the file writable
<category> can be one of

set_timestamp <integer>

set the update time of the file

file_descriptor

The file_descriptor values, obtained from the file.open function or the create_pipe procedure, can then be used in this constructor.

The -name option allows you to assign a string name to this object.

Procedures

close

close the file

new_line

put a newline to the file

put <arguments>

put the arguments to the file

put_line <arguments>

put the arguments and newline to the file

redirect_stderr

redirect stderr to this file

redirect_stdin

redirect stdin from this file

redirect_stdout

redirect stdout to this file

reposition_current <count>

reposition <count> bytes from current position

reposition_end [<count>]

reposition 0 or <count> bytes from end

reposition_start [<count>]

reposition 0 or <count> bytes from start

synchronize

synchronize changes to file to disk

truncate [<length>]

cause the file to have 0 or <length> bytes

Functions

eof

returns 1 if at end of file

kind

kind of file

position

current byte position

read_bytes <address> <count>

read <count> bytes to <address>
returns amount read

value

integer descriptor value

write_bytes <address> <count>

write <count> bytes from <address>
returns amount written

Examples

The following is a fragment from a program which starts the UNIX ftp program as a subprocess and uses pipes to communicate with it.

file_stream

The file_descriptor values, obtained from the file.open function or the create_pipe procedure, can be used in this constructor. The open_stream operator on file objects returns an object of this type. The -name option allows one to assign a string name to this object which the name operator will return.

Procedures

close

close the file

flush

flush file to disk

new_line

put a newline to the file

put <arguments>

put the arguments to the file

put_line <arguments>

put the arguments and newline to the file

reposition_current <count>

reposition <count> bytes from current position

reposition_end [<count>]

reposition 0 or <count> bytes from end

reposition_start [<count>]

reposition 0 or <count> bytes from start

Functions

descriptor

return integer value of file descriptor

eof

returns 1 if at end of file

get_char

returns next character from the stream

get_line

returns next line from the stream

position

current byte position

Examples

Create a file and write text to it:

Read each line of a file:

file_string_map

A file_string_map is a string_map that's represented in a file.

If a filename is given in the declaration, the file is read at that point.

Procedures

set_name <filename>

set the filename associated with the map

read

read from the file

write

write to the file
plus all of the string_map operations

input_file

The input_file is an interface to read a text file. Operators from the type file can also be used on objects of this type.

Options

-comments

remove # comment lines

-includes

- allow #include directives

-continuations

- consume \ line end continuations

-conditionals

- allow #ifdef's and #defines

Procedures

close

close the file

error_message <args>

generate an error message that includes the current filename and line number

warning_message <args>

generate a warning message that includes the current filename and line number

define <var> [<value>]

add a variable to the file's defined set

get_line <var_name>

read the next line into the given variable

next_token <var_name>

read the next token into the given variable

set_token <value>

set the next token to be read to the given value

Functions

get_line

read the next line

eof

returns 1 after a Get_Line has detected end of file

line_number

current Line_Number

next_token

get next token from file, transparently skips newlines

rest_of_line

rest of a line from file being read in token mode

token_quoted

was the last token that was read double quoted

descriptor

get the integer file_descriptor of the file

replace_variables <value>

replace $varnames in the given value with defined variables from the file's defined set

output_file

An output_file is an interface to write a text file. Operators from the type file can also be used on objects of this type.

Procedures

put <args>

if multiple args each is put with one space between

put_line <args>

like put with a New_Line added

new_line

terminate a line

close

close the file

flush

flush the file

put_line_variable <var_name>

put the contents of the given variable followed by a newline

put_variable <var_name>

put the contents of the given variable

Functions

descriptor

get the integer file_descriptor of the file

request

A request is an interface to the Apex interprocess message type. The Server_Name is the name of a registered Apex server. It should be the null string for requests sent to the Apex_Message_Server or for uses of this type in a non Apex session context.

The operation can be the string image of a built-in operation name or it can be an integer. The -size option specifies that a request object with the given size is to be preallocated.

Examples using request and connect are provided in the Examples chapter.

Procedures

add_other_part <value>

add the Other_Part info to a request

append <string>

append a string to the request

append_boolean <number>

append a 1 byte boolean to the request

append_chars <string>

append bytes from the string directly to the request

append_long <number>

append an 4 byte integer to the request

call <connection> [<max_wait>]

send the request using the given "connection" object and do a receive waiting for a response
wait for <max_wait> seconds or unlimited, if not given

make_empty

set the current size to 0
reset for sending

receive <connection> [<max_wait>]

waiting on the given connection for a message
wait for <max_wait> seconds or unlimited if not given

reset_seen

reset the seen iterator for the get operations

send <connection>

send the request using the given Connection object

set_data_size

set the data size value of the request
a request can be declared to be of some large initial size, fill in part of it, and then specify that size with this procedure

set_operation <value>

set the operation part of a request

set_server <name>

set the server_name part of a request

set_server_required

set the Server_Required bit in the request
when set and the named server does not exist, it will not be started

Functions

data_length

get the length of the data area in the request

data_start

get the address of the start of the data area in the request

get

get a string from the request

get_boolean

get a 0 or 1 boolean from the request

get_long

get an integer from the request

integer_operation <string>

get the integer value for a operation name

more

are there more parameters in the request

operation

get the operation name (or number if not known) from the request

operation_number

get the operation number from the request

other_part

get the Other_Part field from the request

server

get the Server_Name part from the request

string

string is the implicit data type for shell variables. There is no explicit constructor for this object type; use the set command instead:

For shell variables whose value is a string (and not a wordlist), the following operations can be applied to the variable. The procedural operators perform the operation directly to the variable's value and are the most efficient way of doing those operations. Some of the functions here are also available as commands in the form funcname $var. The ones here are more efficient.

Procedures

append <value>

append the given <value>

append_variable <var_name>

append the value of the variable named <var_name>

byte <var_name> <index>

get the byte value at <index> and assign the string image of the integer to the variable named <var_name>

capitalize

capitalize the string

char <var_name> <index>

get the character at <index> and assign it as a string to the variable named <var_name>

delete <index> [<count>]

delete <count> characters starting at <index>
default count is 1

ensure_storage <count>

ensure string has space for <count> characters

head <var_name>

assign the first token from string to the variable named <var_name>

insert <index> <value>

insert the given <value> at position <index>

lower

lowercase the string

make_empty

make the string have 0 length

make_printable

quote the string if embedded blanks, double interior quotes

normalize

strip the string and delete trailing slashes (/)

remove_head

remove first token from string

replace <value> <newvalue>

replace occurrences of <value> with <newvalue>

set <index> <value>

replace char at <index> with <value>

set_byte <index> <integer>

replace char at <index> with byte <integer>

skip_whitespace <last_var>

move char pointer denoted by variable last past any white space

strip

remove leading and training spaces

substring <var_name> <start> <count>

extract a substring starting at <start> for <count> characters and assign to <var_name>

tail <var_name>

assign the value after first token from string to the variable named <var_name>

token <var_name> <which>

assign the <which>'th token to <var_name>

upper

uppercase the string

Functions

byte <index>

get the byte value at <index> as an integer

char <index>

get the character at <index>

equals <value>

is the string equal <value>

greater <value>

is the string greater than <value>

greater_equal <value>

is the string greater than or equal to <value>

has_value

is the string nonempty

head

get the first token

is_empty

is the string empty

last

get value of the last index position

length

get the string's length

less <value>

is the string less than <value>

less_equal <value>

is the string less than or equal to <value>

locate <value> [<start>]

locate first occurrence of <value> in string. If <start> is given, start search there

lower

get lowercase copy of the string

make_printable

get Make_Printable copy of the string

next_token <var_name> <last_var> [<quoted_var>]

get next token from string, assign to <var_name>.Assign new index position to <last_var>
return 0 if no more tokens, if token was quoted and <quoted_var> is given, assign it 1

normalize

normalize a file path
removes leading and trailing spaces, and removes trailing slash (/) characters

reverse_locate <value> [<start>]

locate first occurrence of <value> in string starting from end of string, if <start> is given, start search there

strip

get copy of string with leading and trailing spaces removed

substring <start> <count>

get a substring starting at <start> for <count> characters

tail

get the rest of the after the first token

token <which>

get the <which>'th token from string

upper

get uppercase copy of the string

Examples

string_array

A string_array is a flexible array of strings. The lower bound of the index is zero.

If no arguments are given, a newly declared array has length zero. The -size option allows one to specify the number of slots to initially allocate in the array. The -tokens option, given a variable whose value has several tokens, places each token of the value into succeeding elements of the array. The -lines option, given a variable whose value has embedded newlines, places each line of the value into succeeding elements of the array. If arguments are given they are placed into the array. if one of those arguments has multiple tokens, those tokens are each placed into the array.

Procedures

add <value>

increases the array length by one and adds the value to the end.

add_array <array_name>

add the elements from the given array to this one

add_tokens <var_name>

add the tokens in the value of the given variable as separate elements of the array

add_variable <var_name>

add the value of the named variable to the array

delete <index>

remove an element and shortens the length by one

execute [-background] [-context <dirname>]

treat the array as an argv and execute the command

expand_name <name> [<context> [relative]]

filename expansion of the given name in the given context with results added to the array
if present, the third argument relative makes the result names relative to the context

get <var_name> <index>

set the given variable to the <index>'th element of the array

get_environment

add one array element for each item in the environment with spaces separating the name from the value
result is in sorted order

set <index> <value>

overwrites a particular element

image [-printable] [-flat] <var_name>

set the given variable to an image of the array

insert <index> <value>

places a new element at the given index and moves the other elements down one

make_empty

removes all elements.

shorten <count>

remove <count> elements from the end of the array

sort [-caseless]

sorts the array in place
the caseless option causes a case-independent sort

show [-flat]

display the entire array
by default, show adds a newline after each element
the -flat option suppresses newlines to produce a one-line display

Functions

contains <value>

test if the array contains the given value

execute [-background] [-context <dirname>]

treat the array as an argv and execute the command
returns the output from the command as a string

get <index>

retrieve a particular element

index <value>

get the index of the given value, -1 if not present

image [-printable] [-flat]

return array contents as a single string
by default, line-feed characters are inserted between elements
the -flat option suppresses line feeds

length

number of elements in the array

last

index of last element in the array

ordered_insert <value>

for a sorted array, insert the given value in its sorted position and return that index

string_map

A string_map is a hashed map of string -> string associations

Procedures

bind <domain> <range>

add an association to the map

unbind <domain>

remove an association from the map

make_empty

make the map be empty

get_range <var_name> <domain>

set the given variable to the range value for the given domain value

Functions

cardinality

number of associations in the map

is_bound <domain>

if the given domain value in the map

get_range <domain>

get the range value associated with the given domain value, null string result if not present

string_set

A string_set is a hashed set of strings

Procedures

add <value>

add an element to the set

remove <value>

remove an element from the set

make_empty

make the set have no members

Functions

cardinality

number of elements in the set

contains <value>

does the set contain the given value

subsystem

A subsystem is an interface to an apex subsystem. Operators from the type directory can also be used on objects of type Subsystem.

The pathname can be a subsystem name or an object within a subsystem

Functions

element_names <history_name>

list of all element names

history_names

list of all simple history names

switch <name>

value from a subsystem switch file

switch_map

string_map of all the switch values; object in which domain is the switch name and range is the switch value

view_names

list of full pathnames of all views in the subsystem

all_attributes

string_map of user-defined attributes for the subsystem; object in which domain is attribute name and range is attribute type

attribute_names

string_array containing the names of all user-defined attributes in the subsystem

attribute_alternative_values <attribute_name>

value list of enum type attribute or current date of date type attribute

attribute_type <attribute_name>

attribute type of the specified user-defiend attribute for this subsystem

attribute <attribute_name>

attribute value of the specified user-defiend attribute for this subsystem

Examples

task

A task is an interface to a Summit task object This object type is effective only when Summit task management is enabled.

Functions

domain_name

full pathname of the task domain of the task

kind

simple name of the task kind

parent

pathname of parent task, if any

children

pathnames of the children tasks, if any

field_names

field names of this task kind

field <field_name>

value of the named field

field_is_list <field_name>

is the named field a list-valued field

field_type <field_name>

type name of the named field

enum_values <field_name>

enumeration values of the named field's type if any

less <field_name> <value>

is the named field < the given value

less_equal <field_name> <value>

is the named field <= the given value

greater <field_name> <value>

is the named field > the given value

greater_equal <field_name> <value>

is the named field >= the given value

user_roles

list of roles that the current user is a member of with respect to the given task

have_roles <role_names>

is the current user a member of all of the specified roles with respect to the given task
the argument may be a single role name or a string enclosed in quotes containing a list of role names separated by spaces

time_value

A time_value is used for manipulating dates/times.

Functions

image [<format_string>]

Presentation image of a Time_Value

value

Integer representation of a Time_Value

version

A version is an interface to a specific instance of an element of a subsystem

Functions

subsystem_name

subsystem name from the version handle

element_name

view relative name of this object

history_name

history name from the version handle

version_number

version number from the version handle

ancestor_copy_count

ancestor_element_name

ancestor_history_name

ancestor_subsystem_name

ancestor_version_number

all_attributes

string_map of user-defined attributes; object in which domain is attribute name and range is attribute value

attribute_value <attribute_name>

attribute value of the specified user-defined attribute for this version

checked_in_when

value of this system-defined attribute

checked_in_who

value of this system-defined attribute

checked_out_when

value of this system-defined attribute

checked_out_who

value of this system-defined attribute

executable

value of this system-defined attribute

expunged

value of this system-defined attribute

migration_revision

value of this system-defined attribute

rcs_version

value of this system-defined attribute

status

value of this system-defined attribute

tasks

value of this system-defined attribute

where

value of this system-defined attribute

view

A view is an interface to an apex view. Operators from the type directory can also be used on objects of this type.

Pathname can be a view name or an object within a view

Functions

subsystem_name

pathname of the enclosing subsystem

subsystem_relative_name

subsystem relative path of the view

subsystem

"subsystem" object of the enclosing subsystem

kind

view's kind

model

view's model pathname

storage

pathname of view's storage

access_category

view's access category

domain_name

view's domain name

host_architecture

view's host architecture property

target_architecture

view's target architecture property

languages

view's languages property

build_key

view's Build_Key switch value

build_policy

view's Build_Policy switch value

default_export_set_name

view's default Export_Set name

default_history_name

view's default history name

switch_file

path to the view's switch file

switch <name>

value of the specified switch in this view

switch_map

string_map of all the switch values; object in which domain is the switch name and range is the switch value

property <name>

value of the specified view property

imports

full pathnames of direct and mutual imports

direct_imports

full pathnames of direct imports

mutual_imports

full pathnames of mutual imports

closure_imports

full pathnames of closure imports

all_imports

full pathnames of direct, mutual, and closure imports

export_set_names

simple names of all Export_Sets

export_set_files

full pathnames of user Export_Set files

export_set_system_files

full pathnames of system Export_Set files

export_set <name>

view relative names of the items in the given Export_Set

imported_export_set_name <imported_view>

name of the export set associated with the given imported view

main_program_names

full pathnames of C++ main programs

object_names

full pathnames of all controlled objects

Functions

attribute <attribute_name>

attribute value of the specified user-defined attribute for this object

window

A window is an interface to an apex editor window from within a Menu_Item action

Procedures

Any operation that is available thorough the Window_Perform procedure can be used. This varies with the editor.

No list available at this time.

Functions

Any of the substitution prompts can be used as a nullary function.

Any operation that is available thorough the Window_Query procedure can be used.


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2001, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS