![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Apex Shell Object Types
Standard OperationsThis chapter describes the object types and operations available in Apex Shell.
There are several operations that are standard for all object types.
Procedures
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.
string_set v v.operations
Displays an image of the object.
Deletes the object, "undeclares" the object name, and frees up memory used by the object.
Functions
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.
Returns 1 if an error condition has been set for the object.
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):
m1.iterate while (! `m1.done`) set domain = `m1.current` set range = `m1.get_range $domain` m1.next endAssignment
Some object types support assignment directly from one object to another. For example:
a1.assign a2
assigns an object a2 to object a1. The argument a2 must be the same object type as a1.
Object TypesThe following Object Types are discussed in this chapter:
byte_string
- configuration
- connection
- directory
- element
- file
- file_descriptor
- file_stream
- file_string_map
- input_file
- output_file
- request
- string
- string_array
- string_map
- string_set
- subsystem
- task
- time_value
- view
- version
- window
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.
byte_string v [ [-size <number
>] <initial_value
> | -address <address
> | -alias <address
> <count
> ]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
byte_string b1 "abcdef xyzw" byte_string b2 -size 100 byte_string b3 -size 200 "initial value" byte_string b4 -address `b1.start` byte_string b5 -alias `b2.start` 50Procedures
append a long using Host_To_Net conversion
delete <count> bytes starting at <index>
the default count is 1ensure array has space for <count> bytes
extend the length of array by <count>
insert the given <value> at position <index>
insert_bytes <index> <address> <length>
insert <length> bytes which start at <address> into array at position <index>
replace byte(s) starting at <index> with <string>
replace byte at <index> with byte <integer>
set_bytes <index> <address> <length>
replace <length> bytes starting at <index> with those from <address>
Functions
get the byte at <index> as an integer string
get the character value at <index>
get the 4 bytes at <index> as an integer string
get the 4 bytes at <index> and do Net_To_Host
get value of the last index position
get the storage length of the array
get the address of the start byte of the array
get a substring starting at <start> for <count> characters
Examples
bs1.set 5 ZZZ bs1.set_byte 3 101 bs2.insert 3 AAA byte_string temp "TEMP" bs1.insert_bytes 1 `temp.start` 3 bs3.set_bytes 3 `temp.start` 3 bs6.delete 4 12 b0.append ABCDEF b0.append_byte 23 b0.append " value2" b0.append_long 789 b0.append_htonl 1234 echo `b0.char 0``b0.char 1` `b0.byte 6` \ `b0.substring 7 7` `b0.get_long 14` `b0.get_ntohl 18`configuration
A configuration is an interface to an apex configuration file
configuration v <pathname
>Functions
full pathnames of the views in the configuration
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.
connection v [-non_blocking] [-persistent] [ -receive | -port <number
> | <host:port
> | <host
> <port
> ]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.
connection c1 "$APEX_MESSAGE_SERVER" connection c2 -persistent "$APEX_MESSAGE_SERVER" connection c3 mercury 32813 connection rc1 -port 12347 connection rc2 -receive
Procedures
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>]]
Functions
do an accept on the socket
if successful, returns a new connection objecthost number from the socket in decimal
integer kind of the connection
read bytes into the variable given
returns count of the bytes readread bytes from the connection.
returns count of the bytes readwrite a string into the connection
returns count of the bytes writtenwrite bytes into the connection
returns count of the bytes writtenExample - having a shell script register as a job or server with Apex
if (! $?APEX_MESSAGE_SERVER) then set info = `apex_display get_root_property APEX_MESSAGE_SERVER` else set info = "$APEX_MESSAGE_SERVER" endif connection conn "$info" if (`conn.fail`) then echo CONNECT FAILED: `conn.error` exit 1 endif conn.job_start "jobs window line" or conn.register Server_Name Example - reading from a socket at the byte level connection rconn -receive if (`rconn.fail`) then echo RECEIVE CONNECT: `rconn.error` exit 1 endif set value = `rconn.image` apex_display set_root_property SERVER_TEST "$value" byte_string buf -size 4000 while (1) set newconn = `rconn.accept` if (`rconn.fail`) then echo ACCEPT FAILED: `rconn.error` exit 1 endif set start = `buf.start` set amount = `$newconn.read_bytes "$start" 50` if (`$newconn.fail`) then echo READ FAILED: `$newconn.error` exit 1 endif # ... $newconn.destroy endExample - writing to a socket at the byte level
set info = `apex_display get_root_property SERVER_TEST` connection sconn "$info" if (`sconn.fail`) then echo CONNECT FAILED: `sconn.error` exit 1 endif byte_string buf -size 10000 # fill in buffer ... set start = `buf.start` set amount = `sconn.write_bytes "$start" 100`directory
A directory is an interface to a UNIX directory object.
directory v [-create] <pathname
>Functions
enclosing subsystem full pathname
user name of the object's owner
time of last modification as an integer
value of the link, if object is a link
full pathname of the value of the link, if object is a link
simple names of the items in the directory
Procedures
filesystem delete of the object
filesystem rename of the object
element
An element is an interface to an object of a subsystem
element v <subsystem_name
> <element_name
> <history_name
>Functions
first version number of the element
last version number of the element
count of the number of versions
subsystem name from the element handle
element name from the element handle
history name from the element handle
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.
file v [-create] <pathname
>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
returns the full, canonical pathname of the file
enclosing subsystem full pathname
filename of the corresponding (object) code file
view_relative name of this object
CMVC status of the latest version of this object
version number of the latest version of this object
returns a "version" object for this object
user name of the object's owner
time of last modification as an integer
the result can be interpreted using the time_value objectvalue of the link, if object is a link
full pathname of the value of the link, if object is a link
attribute value of the specified user-defined attribute for this object
is the file a header, c, or C++ file
is the file a header or C++ file
ada, c, or C++ Other_Part filename
editor associated with this kind of object
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.
like the open operator but returns a file_stream object
Procedures
filesystem delete of the object
filesystem rename of the object
Status results will be one of the values:
Not_In_A_View
Uncontrolled
Checked_In
Checked_Out
Private
Deletedmake_nonexecutable [<category>]
make the file writable
<category> can be one ofuser_only
user_group
user_public
group_only
group_public
structure
system
subsystem
view
public
private
unmanaged
preserveset the update time of the file
file_descriptor
file_descriptor v [ [-name <string
>] <integer_descriptor_of_open_file
> ]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.
set fds = (`create_pipe`)
file_descriptor fdr "$fds[1]"
file_descriptor fdw "$fds[2]"Procedures
put the arguments and newline to the file
reposition <count> bytes from current position
reposition 0 or <count> bytes from end
reposition 0 or <count> bytes from start
synchronize changes to file to disk
cause the file to have 0 or <length> bytes
Functions
read <count> bytes to <address>
returns amount readwrite <count> bytes from <address>
returns amount writtenExamples
file f1 -create /tmp/foo set outf = `f1.open` $outf.put_line line1 text $outf.put line2 text $outf.new_line $outf.close #----------- file f1 /tmp/foo set inf = `f1.open -read` byte_string bs bs.extend 7 set start = `bs.start` while (! `$inf.eof`) set amount = `$inf.read_bytes "$start" 6` bs.set_byte "$amount" 0 # ... end $inf.close #----------- byte_string bs -size 500 for (set x = 0; "$x" < 500; @ x++) bs.append a end file f2 -create /tmp/abc set fd = `f2.open -write` set start = `bs.start` set amount = `$fd.write_bytes "$start" 500` #----------- file f1 -create /tmp/foobar set outf = `f1.open` $outf.redirect_stdout echo redirected line1 text echo redirected line2 $outf.close #-----------The following is a fragment from a program which starts the UNIX ftp program as a subprocess and uses pipes to communicate with it.
set send_pipe = (`create_pipe`) set rcv_pipe = (`create_pipe`) apex_display execute -same_machine -no_register \ -fdin "$send_pipe[1]" \ -fdout "$rcv_pipe[2]" \ ftp -i -v & file_descriptor t1 "$send_pipe[1]" t1.close file_descriptor t1 "$rcv_pipe[2]" t1.close file_descriptor sendfd "$send_pipe[2]" file_stream rcvfd "$rcv_pipe[1]" sendfd.put_line open "$some_machine_name" sendfd.put_line "$some_command" while (1) set line = `rcvfd.get_line` # process each output line from subprocess ... endfile_stream
file_stream v [ [-name <string
>] <integer_descriptor_of_open_file
> ]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
put the arguments and newline to the file
reposition <count> bytes from current position
reposition 0 or <count> bytes from end
reposition 0 or <count> bytes from start
Functions
return integer value of file descriptor
returns next character from the stream
returns next line from the stream
Examples
Create a file and write text to it:
file f1 -create /tmp/foo set outs = `f1.open_stream -write` $outs.put_line line1 text $outs.put line2 text $outs.new_line $outs.close
file f1 /tmp/foo set ins = `f1.open_stream -read` while (! `$ins.eof`) set line = `$ins.get_line` # ... end $ins.closefile_string_map
A file_string_map is a string_map that's represented in a file.
file_string_map v [-upper | -lower] [-size <hash_table_size
>] [<filename
>]If a filename is given in the declaration, the file is read at that point.
Procedures
set the filename associated with the map
write to the file
plus all of the string_map operationsinput_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.
input_file v [option*] <filename
>Options
- consume \ line end continuations
Procedures
generate an error message that includes the current filename and line number
generate a warning message that includes the current filename and line number
add a variable to the file's defined set
read the next line into the given variable
read the next token into the given variable
set the next token to be read to the given value
Functions
returns 1 after a Get_Line has detected end of file
get next token from file, transparently skips newlines
rest of a line from file being read in token mode
was the last token that was read double quoted
get the integer file_descriptor of the file
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.
output_file v [-append] <filename
>Procedures
if multiple args each is put with one space between
like put with a New_Line added
put the contents of the given variable followed by a newline
put the contents of the given variable
Functions
get the integer file_descriptor of the file
request
request v [-size <number
>] [<server_name
> [<operation
>]]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.
request r1 "" set_value request r2 My_Server 10001 request r3 Apex_Directory_Server editor_operation request r4 -size 4000Examples using request and connect are provided in the Examples chapter.
Procedures
add the Other_Part info to a request
append a string to the request
append a 1 byte boolean to the request
append bytes from the string directly to the request
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 givenset the current size to 0
reset for sendingreceive <connection> [<max_wait>]
waiting on the given connection for a message
wait for <max_wait> seconds or unlimited if not givenreset the seen iterator for the get operations
send the request using the given Connection object
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 procedureset the operation part of a request
set the server_name part of a request
set the Server_Required bit in the request
when set and the named server does not exist, it will not be startedFunctions
get the length of the data area in the request
get the address of the start of the data area in the request
get a 0 or 1 boolean from the request
get an integer from the request
get the integer value for a operation name
are there more parameters in the request
get the operation name (or number if not known) from the request
get the operation number from the request
get the Other_Part field from the request
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:
set var = <string expression
>
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 the value of the variable named <var_name>
get the byte value at <index> and assign the string image of the integer to the variable named <var_name>
get the character at <index> and assign it as a string to the variable named <var_name>
delete <count> characters starting at <index>
default count is 1ensure string has space for <count> characters
assign the first token from string to the variable named <var_name>
insert the given <value> at position <index>
quote the string if embedded blanks, double interior quotes
strip the string and delete trailing slashes (/)
remove first token from string
replace occurrences of <value> with <newvalue>
replace char at <index> with <value>
replace char at <index> with byte <integer>
move char pointer denoted by variable last past any white space
remove leading and training spaces
substring <var_name> <start> <count>
extract a substring starting at <start> for <count> characters and assign to <var_name>
assign the value after first token from string to the variable named <var_name>
assign the <which>'th token to <var_name>
Functions
get the byte value at <index> as an integer
is the string greater than <value>
is the string greater than or equal to <value>
get value of the last index position
is the string less than <value>
is the string less than or equal to <value>
locate first occurrence of <value> in string. If <start> is given, start search there
get lowercase copy of the string
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 1normalize a file path
removes leading and trailing spaces, and removes trailing slash (/) charactersreverse_locate <value> [<start>]
locate first occurrence of <value> in string starting from end of string, if <start> is given, start search there
get copy of string with leading and trailing spaces removed
get a substring starting at <start> for <count> characters
get the rest of the after the first token
get the <which>'th token from string
get uppercase copy of the string
Examples
var.strip var.set 3 Z var.set 6 ABC var.set_byte 3 101 set pos = `var.locate '/'` #--- set last = -1 set ignore = `var.next_token temp last` var.skip_whitespace last @ next = "$last" + 1 @ len = `var.length` - "$next" var.substring rest "$next" "$len" #--- set last = -1 while (`var.next_token temp last`) echo token = "$temp" end #--- set ver = "$APEX_PROD_VERSION" if (`ver.greater_equal 2.3.0`) then ... endifstring_array
A string_array is a flexible array of strings. The lower bound of the index is zero.
string_array v [-size <number
>] [ -tokens <varname
> | -lines <varname
> | <initial_values
> ]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.
set names = `some_function arg1 arg2` string_array a1 -tokens names string_array a2 `get_values arg`Procedures
increases the array length by one and adds the value to the end.
add the elements from the given array to this one
add the tokens in the value of the given variable as separate elements of the array
add the value of the named variable to the array
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 contextset the given variable to the <index>'th element of the array
add one array element for each item in the environment with spaces separating the name from the value
result is in sorted orderoverwrites a particular element
image [-printable] [-flat] <var_name>
set the given variable to an image of the array
places a new element at the given index and moves the other elements down one
remove <count> elements from the end of the array
sorts the array in place
the caseless option causes a case-independent sortdisplay the entire array
by default, show adds a newline after each element
the -flat option suppresses newlines to produce a one-line displayFunctions
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 stringget the index of the given value, -1 if not present
return array contents as a single string
by default, line-feed characters are inserted between elements
the -flat option suppresses line feedsnumber of elements in the array
index of last element in the array
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
string_map v [-upper | -lower] [-size <hash_table_size>]
-upper all domain values are stored in uppercase
-lower all domain values are stored in lowercase
Procedures
remove an association from the map
set the given variable to the range value for the given domain value
Functions
number of associations in the map
if the given domain value in the map
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
string_set v [-upper | -lower] [-size <hash_table_size>]
-upper all members are stored in uppercase -lower all members are stored in lowercase
Procedures
remove an element from the set
Functions
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.
subsystem v <pathname
>The pathname can be a subsystem name or an object within a subsystem
Functions
list of all simple history names
value from a subsystem switch file
string_map of all the switch values; object in which domain is the switch name and range is the switch value
list of full pathnames of all views in the subsystem
string_map of user-defined attributes for the subsystem; object in which domain is attribute name and range is attribute type
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 value of the specified user-defiend attribute for this subsystem
Examples
subsystem ss $full_pathname set history = Common foreach elem ('subsystem.element_names $history') do_someting $elem endtask
A task is an interface to a Summit task object This object type is effective only when Summit task management is enabled.
task v <pathname
>Functions
full pathname of the task domain of the task
pathname of parent task, if any
pathnames of the children tasks, if any
is the named field a list-valued field
enumeration values of the named field's type if any
is the named field < the given value
less_equal <field_name> <value>
is the named field <= the given value
is the named field > the given value
greater_equal <field_name> <value>
is the named field >= the given value
list of roles that the current user is a member of with respect to the given task
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 spacestime_value
A time_value is used for manipulating dates/times.
time_value v { "time_image" | -value <integer
> ) time_value v1 # current time time_value v2 "11/12/95 23:17:34" time_value v3 -value 825471100Functions
Presentation image of a Time_Value
Integer representation of a Time_Value
echo `v1.image %m/%d/%y` echo `v2.image %H:%M:%S` set internal = `v2.value`
version
A version is an interface to a specific instance of an element of a subsystem
version v <subsystem_name> <element_name> <history_name> <version_number>Functions
subsystem name from the version handle
view relative name of this object
history name from the version handle
version number from the version handle
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
value of this system-defined attribute
value of this system-defined attribute
value of this system-defined attribute
value of this system-defined attribute
value of this system-defined attribute
value of this system-defined attribute
value of this system-defined attribute
value of this system-defined attribute
value of this system-defined attribute
value of this system-defined attribute
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.
view v <pathname
>Pathname can be a view name or an object within a view
Functions
pathname of the enclosing subsystem
subsystem relative path of the view
"subsystem" object of the enclosing subsystem
view's host architecture property
view's target architecture property
view's Build_Policy switch value
view's default Export_Set name
path to the view's switch file
value of the specified switch in this view
string_map of all the switch values; object in which domain is the switch name and range is the switch value
value of the specified view property
full pathnames of direct and mutual imports
full pathnames of direct imports
full pathnames of mutual imports
full pathnames of closure imports
full pathnames of direct, mutual, and closure imports
simple names of all Export_Sets
full pathnames of user Export_Set files
full pathnames of system Export_Set files
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
full pathnames of C++ main programs
full pathnames of all controlled objects
Functions
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
window v <alias_key
>
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. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |