Bull HN Product Differences Guide THE MULTICS/UNIX PRODUCT DIFFERENCES GUIDE PREPARED BY: ACTC TECHNOLOGIES INC. DATE: MARCH 11, 1991 SUBJECT Product differences between Multics subroutines and commands and their UNIX equivalents. SPECIAL INSTRUCTIONS This guide assumes basic knowledge of the Multics and UNIX operating systems. 03/11/91 i Product Differences Guide Bull HN PREFACE _P_u_r_p_o_s_e _a_n_d _A_u_d_i_e_n_c_e The purpose of this guide is to help Multics users migrate their software to the Bull HN UNIX system. It provides information on the significant differences between Multics subroutines and commands and their ported equivalents on the Bull HN UNIX system. It is assumed that the reader of this guide is familiar with Multics and its subroutines and commands; this document does not provide complete descriptions and is not intended as a tutorial document. For full documentation on a particular command/subroutine, access the information file related to the command/subroutine through the help facility (i.e. type "help subroutine_name"). _H_o_w _t_h_i_s _m_a_n_u_a_l _i_s _o_r_g_a_n_i_z_e_d Section 1 is the Introduction. Section 2, the Quick Reference section, gives a brief description of each subroutine or command that has been ported to UNIX. If the differences are extensive, you will be referred to another section in the guide. The descriptions are organized in the following format: Command/Subroutine: gives the UNIX name of the command or subroutine that has been ported. Function: gives a brief description of the function of the command/subroutine. Syntax: gives the declaration and usage of the UNIX command/subroutine. Multics Equivalent: gives the Multics name of the command/subroutine that has been ported. Differences: describes how the newly implemented command/subroutine is different from the original on Multics. Info File: gives the name of the corresponding information file if one exists. Sections 3 to 10 give, in detail, the differences in the UNIX implementations of Multics commands/subroutines for major products of the Migration package. ii 03/11/91 Bull HN Product Differences Guide _C_o_n_v_e_n_t_i_o_n_s _u_s_e_d _i_n _t_h_i_s _m_a_n_u_a_l a. Multics Manuals are referred to by their explicit order numbers. UNIX Manuals are referred to by an entry name and section number. For example printf(3) refers to the entry printf in section 3 of the standard UNIX manuals. b. Braces {} are used in this manual to enclose information from which the user must make a choice. For example command {control arguments} argument _C_o_p_y_r_i_g_h_t _I_n_f_o_r_m_a_t_i_o_n Copyright, (C) Bull-HN Information Systems Inc, 1990. _T_r_a_d_e_m_a_r_k _I_n_f_o_r_m_a_t_i_o_n UNIX is a registered trademark of AT&T Bell Laboratories. 03/11/91 iii Product Differences Guide Bull HN _T_A_B_L_E _O_F _C_O_N_T_E_N_T_S _S_e_c_t_i_o_n _S_u_b_j_e_c_t _P_a_g_e 1 Introduction 1 2 Quick Reference to Subroutines and Commands 2 3 cdo Differences 50 3.1 . . Summary 50 3.2 . . Filenames 50 3.3 . . Control Arguments 50 3.4 . . Source File Format 50 4 cet Differences 52 4.1 . . Summary 52 4.2 . . Control arguments 52 4.3 . . Filenames 53 5 Help Differences 54 5.1 . . Naming Conventions 54 5.2 . . System Info Files 55 5.3 . . Search Paths 55 5.4 . . Special Characters 56 5.5 . . Program Libraries 57 6 pl1 Command Differences 58 6.1 . . Summary 58 6.2 . . Differences in Arguments 58 6.3 . . Differences in Control Arguments 58 6.4 . . Differences in Filenames 60 6.5 . . Creation of Object Files 61 7 PL/I Language Differences 62 7.1 . . Summary 62 7.2 . . Data Types 62 7.3 . . Altered Storage Types 66 7.4 . . Conditions 68 7.5 . . Builtins 72 7.6 . . Extensions to PL/I 76 7.7 . . Efficiency Considerations 80 8 uassign_ Differences 82 8.1 . . Summary 82 8.2 . . Parameter Differences 82 8.3 . . UNIX Data Types 83 9 uiox_ Differences 84 9.1 . . Name Changes 84 9.2 . . Parameter Changes 84 9.3 . . Unsupported Operations 84 9.4 . . New Operations 85 9.5 . . Renamed Operations 85 9.6 . . Concurrent vs Sequential Multiprocessing 85 9.7 . . Attach Table 86 9.8 . . Static Switch Initialization 86 9.9 . . Operation Under UNIX 87 9.10 . . Locating An I/O Module 87 10 vfile_ Differences 88 10.1 . . Unsupported vfile_ Arguments 88 iv 03/11/91 Bull HN Product Differences Guide 10.2 . . Supported File Types 88 10.3 . . Unsupported Control Orders 89 10.4 . . New Control Orders 89 10.5 . . Multiple Openings 90 10.6 . . Record Locking 91 10.7 . . Record Descriptors and User Reference Count 91 10.8 . . Control Orders 92 03/11/91 v Bull HN Product Differences Guide 1. _I_N_T_R_O_D_U_C_T_I_O_N The source and target operating systems -- Multics and UNIX -- are different in many respects. These differences have a direct effect on the interface and functionality of the commands and subroutines ported to UNIX from Multics. The major differences between a Multics command/subroutine and its UNIX equivalent are generally related to hardware differences and differences between operating system capabilities and user interface. The following sections are your guide to these specific differences. (For more general discussion of Multics/UNIX differences, see the "Multics to UNIX Migration Guide.") 03/11/91 1 Product Differences Guide Bull HN 2. _Q_U_I_C_K _R_E_F_E_R_E_N_C_E _T_O _S_U_B_R_O_U_T_I_N_E_S _A_N_D _C_O_M_M_A_N_D_S _________________________________________________________________ Command/Subroutine: create_data_object_ Function: Called from within a cdo source program to create the UNIX object file. Syntax: declare create_data_object_ entry (char (*), ptr, fixed bin (15), fixed bin (31)); call create_data_object_ (pathname, addr (item_array), NUMBER_OF_ITEMS, error_code); Multics Equivalent: Similiar in function to create_data_segment_. Differences: See section 3. Info File: cdo_.i, cdo.i _________________________________________________________________ Command/Subroutine: cdo Function: Translates a cdo source file into a UNIX Common Object File Format (COFF) object file. The result is placed in the working directory. Syntax as a command: cdo path Multics Equivalent: create_data_segment, cds Differences: See section 3. Info File: cdo.i, cdo_.i 2 03/11/91 Bull HN Product Differences Guide _________________________________________________________________ Command/Subroutine: cet Function: cet translates a Multics ALM (Multics assembly language) error table source file into a UNIX Common Object File Format (COFF) object file. Syntax as a command: cet path {-control_arguments} Multics Equivalent: ALM (as used for compiling error tables). Differences: See section 4. Info File: cet.i _________________________________________________________________ Command/Subroutine: help Function: prints descriptions of system commands and subroutines as well as miscellaneous information about system status, system changes, and general information. Help selects this information from files maintained online; these are in a special format called info files. Syntax as a Command: help {info_names} {-control_args} Multics Equivalent: help Differences: See section 5. Info File: help.i help.g.i help_infos.i help_resp.i info_seg.i info_segs.i topics.i 03/11/91 3 Product Differences Guide Bull HN _________________________________________________________________ Command/Subroutine: list_help, lh Function: displays the names of all info files pertaining to a given topic. Syntax as a Command: lh topics {-control_args} Multics Equivalent: list_help, lh Differences: None. Info File: list_help.i _________________________________________________________________ Command/Subroutine: pl1 Function: UNIX compiler for the pl1 language. Syntax as a command: pl1 path {-control_args} Multics Equivalent: pl1 Differences: See sections 6 and 7. Info File: pl1.i _________________________________________________________________ Command/Subroutine: rdc Function: generates language translations. rdc compiles a file containing reductions and action routines into a PL/I source file; it then invokes the PL/I compiler to compile the PL/I source. The reductions specify the syntax and semantics of a new language; the action routines perform the basic operations (e.g. semantic code) required to translate the language. Syntax as a command: rdc path {-control_args} Multics Equivalent: reductions, rdc 4 03/11/91 Bull HN Product Differences Guide Differences: The UNIX rdc command is functionally equivalent to the Multics original. However, the format of the source file is considerably different. Since the source is a PL/I program, it is subject to the same porting considerations as any other PL/I program. To perform lexical analysis on the reductions file, a source file for UNIX rdc must do the following: 1) Make a call to the UNIX "fstat" routine to determine the length of the reductions file. 2) Obtain storage for the reductions file by calling the UNIX "malloc" routine. 3) Read the reductions file into the storage, and then call the "ulex_string_" routine to perform lexical analysis on it. The suffixes of input and output files used by UNIX rdc differ from those used by Multics rdc. The UNIX rdc suffix is ".r" and the intermediate PL/I file will have a suffix of ".p". A new control argument has been added for UNIX rdc: -pl1_args arguments specifies a list of control arguments to be passed to the pl1 compiler. If given, this control argument must appear last on the command line. Info File: rdc.i _________________________________________________________________ Command/Subroutine: uabsolute_pathname_ Function: converts a relative or absolute pathname into a full absolute pathname. Syntax: declare uabsolute_pathname_ entry (char(*), char(*), fixed bin (31)); call uabsolute_pathname_ (pathname, full_pathname, code); Multics Equivalent: absolute_pathname_ Differences: The code parameter which holds the standard status code is changed from fixed bin(35) on Multics to fixed bin(31) on UNIX. The maximum length for the absolute pathname has increased from 168 characters on Multics to 255 characters on the BULL XPS UNIX system. 03/11/91 5 Product Differences Guide Bull HN An additional feature has been created to allow the use of UNIX pathname conventions. A change in the syntax of the pathname has been made: the substitution of ">" and "<" on Multics to "/" and "../" on BULL XPS UNIX. A number of successive forward slashes (/) is allowed. The string "./" is interpreted correctly to mean "stay in the current directory." And finally, the string "../" is interpreted correctly to mean "to specify the parent directory." (i.e. "/user/////mp//tools/path/../../././.../." will be returned as directory = "/user/mp/..." entry = ".") Info File: uabs_path_.i _________________________________________________________________ Command/Subroutine: uabsolute_pathname_$add_suffix Function: expands a relative or absolute pathname into a full, absolute pathname, adding a suffix to the entryname if that suffix is not already present. Syntax: declare uabsolute_pathname_$add_suffix entry (char(*), char(*), char(*), fixed bin (31)); call uabsolute_pathname_$add_suffix (pathname, suffix, full_pathname, code); Multics Equivalent: absolute_pathname_$add_suffix Differences: The code parameter which holds the standard status code is changed from fixed bin(35) on Multics to fixed bin(31) on UNIX. The maximum length for the absolute pathname has increased from 168 characters on Multics to 255 characters on the BULL XPS UNIX system. Info File: uabs_path_.i 6 03/11/91 Bull HN Product Differences Guide _________________________________________________________________ Command/Subroutine: uassign_ Function: assigns a specified source value to a specified target. This subroutine handles the data types 2-4, 6-8, 10-18, 20, 22, 25, 27, and 31-38. Any other type will produce an error. (The include file desc_types.i defines these UNIX PL/I data types.) This subroutine uses rounding in conversions when the target is floating point or when the source is floating and the target is character, and uses truncation in all other cases. Syntax: declare uassign_ entry (ptr, fixed bin(15), fixed bin(31), ptr, fixed bin(15), fixed bin(31)); call uassign_ (target_ptr, target_type, target_length, source_ptr, source_type, source_length); Multics Equivalent: assign_ Differences: See section 8. Info File: uassign_.i _________________________________________________________________ Command/Subroutine: uassign_$computational_ Function: assigns a specified source value to a specified target. It can handle any computational data type including all PL/I computational data types. This entry uses the same rules for rounding and truncation as uassign_. Syntax: declare uassign_$computational_ entry (ptr, ptr, fixed bin(31)); call uassign_$computational_ (tar_str_ptr, src_str_ptr, code); Multics Equivalent: assign_$computational_ Differences: See section 8. Info File: uassign_.i 03/11/91 7 Product Differences Guide Bull HN _________________________________________________________________ Command/Subroutine: uassign_$round_ Function: assigns a source value to a target value, but always rounds. Otherwise it is identical to uassign_. Syntax: declare uassign_$round_ entry (ptr, fixed bin(15), fixed bin(31), ptr, fixed bin(15), fixed bin(31)); call uassign_$round_ (target_ptr, target_type, target_length, source_ptr, source_type, source_length); Multics Equivalent: assign_$round_ Differences: See section 8. Info File: uassign_.i _________________________________________________________________ Command/Subroutine: uassign_$truncate_ Function: assigns a source value to a target value, but always truncates. Otherwise it is identical to uassign_. Syntax: declare uassign_$truncate_ entry (ptr, fixed bin(15), fixed bin(31), ptr, fixed bin(15), fixed bin(31)); call uassign_$truncate_ (target_ptr, target_type, target_length, source_ptr, source_type, source_length); Multics Equivalent: assign_$truncate_ Differences: See section 8. Info File: uassign_.i 8 03/11/91 Bull HN Product Differences Guide _________________________________________________________________ Command/Subroutine: ucom_err_ Function: formats an error message and then signals the command_error condition. The default handler for this condition simply returns control to the ucom_err_ subroutine, which then displays the error message. Syntax: declare ucom_err_ entry options (variable); call ucom_err_ (code, caller, control_string, arg1, ..., argN); Multics Equivalent: com_err Differences: 1) code changed to fixed bin (31) 2) accepts 'cet' created error codes 3) accepts valid UNIX error numbers as codes Info File: ucom_err_.i _________________________________________________________________ Command/Subroutine: ucom_err_$suppress_name Function: This entry point should be used when the caller name and colon are not wanted. The caller name is still passed to the command_error condition handler. Otherwise, this entry point is the same as the ucom_err_ entry point. Syntax: declare ucom_err_$suppress_name entry options (variable); call ucom_err_$suppress_name (code, caller, control_string, arg1, ..., argN); Multics Equivalent: com_err_$suppress_name Differences: 1) code changed to fixed bin (31) 2) accepts 'cet' created error codes 3) accepts valid UNIX error numbers as a code Info File: ucom_err_.i 03/11/91 9 Product Differences Guide Bull HN _________________________________________________________________ Command/Subroutine: uconvert_date_to_binary_ Function: converts a character representation of a date and time into a 64-bit clock reading. Syntax: declare uconvert_date_to_binary_ entry (char(*), fixed bin(63), fixed bin(31)); call uconvert_date_to_binary_ (time_string, clock, code); Multics Equivalent: convert_date_to_binary_ Differences: The clock variable has changed from fixed bin(71) on Multics to fixed bin(63) on UNIX. The code parameter which holds the standard status code is changed from fixed bin(35) on Multics to fixed bin(31) on UNIX. Info Seg: ucon_date_bi.i _________________________________________________________________ Command/Subroutine: uconvert_date_to_binary_$relative Function: This entry point is similar to the uconvert_date_to_binary_ entry point, except that the clock reading returned is computed relative to an input clock time rather than the current clock time. Thus, the clock reading returned for the string "March 26" is the clock reading for the first March 26 following the input clock time, rather than the clock reading for the first March 26 following the current clock time. Given a 64-bit clock time to use, this entry point converts a character representation of a date and time to the equivalent 64-bit clock reading. Syntax: declare uconvert_date_to_binary_$relative entry (char(*), fixed bin(63), fixed bin(63), fixed bin(31)); call uconvert_date_to_binary_$relative (string, clock, clock_in, code); Multics Equivalent: convert_date_to_binary_$relative Differences: The clock and clock_in variable has changed from fixed bin(71) on Multics to fixed bin(63) on UNIX. The code parameter which holds the standard status code is changed from fixed bin(35) on Multics to fixed bin(31) on UNIX. 10 03/11/91 Bull HN Product Differences Guide Info Seg: ucon_date_bi.i _________________________________________________________________ Command/Subroutine: ucu_$arg_count Function: The ucu_$arg_count entry point can be used by any procedure to determine the number of arguments which called it. Syntax: declare ucu_$arg_count entry (fixed bin (15), fixed bin (31)); call ucu_$arg_count (arg_count, code); Multics Equivalent: cu_$arg_count Differences: error code changed to fixed bin (31) Info File: ucu_.i _________________________________________________________________ Command/Subroutine: ucu_$arg_count_rel Function: This entry point returns the number of arguments in any specified argument list. Syntax: declare ucu_$arg_count_rel entry (fixed bin (15), ptr, fixed bin (31)); call ucu_$arg_count_rel (arg_count, arg_list_ptr, code); Multics Equivalent: cu_$arg_count_rel Differences: 1) error code changed to fixed bin (31) 2) arg_list.i replaces include file arg_list.incl.pl1 Info File: ucu_.i 03/11/91 11 Product Differences Guide Bull HN _________________________________________________________________ Command/Subroutine: ucu_$arg_list_ptr Function: It is sometimes desirable to design a PL/I procedure to accept a variable number of arguments of varying data types (e.g., the uioa_ subroutine). In these cases, the PL/I procedure must be able to interrogate its argument list directly to determine the number, type, and location of each argument. The ucu_$arg_list_ptr entry point is designed for use in such cases and returns a pointer to the argument list of its caller. Syntax: declare ucu_$arg_list_ptr entry (ptr); call ucu_$arg_list_ptr (arg_list_ptr); Multics Equivalent: cu_$arg_list_ptr Differences: 1) error code changed to fixed bin (31) Info File: ucu_.i _________________________________________________________________ Command/Subroutine: ucu_$arg_ptr Function: The ucu_$arg_ptr entry point is used by a command or subroutine that can be called with a varying number of arguments, each of which is a variable-length unaligned character string (i.e. declared char(*)). This entry point returns a pointer to the character string argument specified by the argument number and also returns the length of the argument. Syntax: declare ucu_$arg_ptr entry (fixed bin (15), ptr, fixed bin (31), fixed bin (31)); call ucu_$arg_ptr (arg_no, arg_ptr, arg_len, code); Multics Equivalent: cu_$arg_ptr Differences: 1) error code changed to fixed bin (31) 2) arg_len changed to fixed bin (31) Info File: ucu_.i 12 03/11/91 Bull HN Product Differences Guide _________________________________________________________________ Command/Subroutine: ucu_$arg_ptr_rel Function: Some PL/I procedures may need to reference arguments passed to other procedures. This entry point permits a procedure to reference arguments in any specified argument list. Syntax: declare ucu_$arg_ptr_rel entry (fixed bin (15), ptr, fixed bin (31), fixed bin (31), ptr); call ucu_$arg_ptr_rel (arg_no, arg_ptr, arg_len, code, arg_list_ptr); Multics Equivalent: cu_$arg_ptr_rel Differences: 1) error code changed to fixed bin (31) 2) new include file arg_list.i replaces arg_list.incl.pl1 3) arg_len changed to fixed bin (31) Info File: ucu_.i _________________________________________________________________ Command/Subroutine: ucu_$caller_ptr Function: This entry point allows a routine to obtain a pointer to its caller. The pointer that is returned points to the instruction within the text section following the instruction that called out. Syntax: declare ucu_$caller_ptr entry (ptr); call ucu_$caller_ptr (caller_ptr); Multics Equivalent: cu_$caller_ptr Differences: none Info File: ucu_.i 03/11/91 13 Product Differences Guide Bull HN _________________________________________________________________ Command/Subroutine: ucu_$cp Function: The ucu_$cp entry point, called when a command line is recognized, passes the command line to the currently defined UNIX shell for processing. Some user commands may permit the user to escape from them to execute other commands. In this case, the escapable command passes the line to be executed to the shell. Syntax: declare ucu_$cp entry (ptr, fixed bin (31), fixed bin (31)); call ucu_$cp (line_ptr, line_len, code); Multics Equivalent: cu_$cp Differences: 1) error code changed to fixed bin (31) 2) line_len changed to fixed bin (31) Notes on ucu_$cp: On UNIX an escape to a shell invokes a new task via the default fork and wait structure. This format will disallow any direct communication with the child shell. Info File: ucu_.i _________________________________________________________________ Command/Subroutine: ucu_$generate_call Function: The ucu_$generate_call entry point is used to generate a standard call to a specified procedure with a specified argument list. This call is designed for cases in which a PL/I procedure has explicitly built an argument list from its input data. The principal use of this entry is by command processors that call a command with an argument list built from a command line input from a terminal. Syntax: declare ucu_$generate_call entry (entry, ptr); call ucu_$generate_call (proc_entry, a_ptr); Multics Equivalent: cu_$generate_call 14 03/11/91 Bull HN Product Differences Guide Differences: new include file arg_list.i replace arg_list.incl.pl1 Info File: ucu_.i _________________________________________________________________ Command/Subroutine: ucu_$make_entry_value Function: The ucu_$make_entry_value entry point constructs a PL/I entry value from a pointer to an entry point. The environment pointer of the entry value will be null, so the entry point pointer must point to an external procedure. Syntax: declare ucu_$make_entry_value entry (pointer, entry); call ucu_$make_entry_value (ep_ptr, entry_value); Multics Equivalent: cu_$make_entry_value Differences: none Info File: ucu_.i _________________________________________________________________ Command/Subroutine: ucu_$decode_entry_value Function: The ucu_$decode_entry_value accepts a PL/I entry variable which it breaks down into the entrypoint pointer and the display or environment pointer. Syntax: declare ucu_$decode_entry_value entry (entry, pointer, pointer); call ucu_$decode_entry_value (entry_value, ep_ptr, env_ptr); Multics Equivalent: cu_$decode_entry_value Differences: none Info File: ucu_.i 03/11/91 15 Product Differences Guide Bull HN _________________________________________________________________ Command/Subroutine: ucu_$gen_call Function: The ucu_$gen_call entrypoint performs a call to an external procedure (pointed to by the procedure pointer argument) and passes it the defined argument list. Syntax: declare ucu_$gen_call entry (pointer, pointer); call ucu_$gen_call (procedure_ptr, arg_list_ptr); Multics Equivalent: cu_$gen_call Differences: arg_list.i replace arg_list.incl.pl1 Info File: ucu_.i _________________________________________________________________ Command/Subroutine: ucu_$ptr_call Function: The ucu_$ptr_call entrypoint calls the defined procedure with the passed arguments. Syntax: declare ucu_$ptr_call entry options (variable); call ucu_$ptr_call (procedure_ptr, arg1, arg2, arg3, ... argn); Multics Equivalent: cu_$ptr_call Differences: none Info File: ucu_.i 16 03/11/91 Bull HN Product Differences Guide _________________________________________________________________ Command/Subroutine: udate_time_ Function: The udate_time_ subroutine converts a system clock value to ASCII representation. This value will be in terms of the per-user-process default language and zone. Syntax: declare udate_time_ entry (fixed bin(63), char(*)); call udate_time_ (clock, str); Multics Equivalent: date_time_ Differences: The clock variable is fixed bin(63) on UNIX, as opposed to fixed bin(71) on Multics. Info Seg: udate_time_.i _________________________________________________________________ Command/Subroutine: udate_time_$format Function: This entry does a generalized formatting of a standard calendar clock value. A format string which describes the layout and content of the desired result is supplied. The zone and/or language in which the result is to be displayed may be specified. Syntax: declare udate_time_$format entry (char(*), fixed bin(63), char(*), char(*)) returns (char(250) var); result = udate_time_$format (time_format, clock, zone, lang); Multics Equivalent: date_time_$format Differences: The clock variable is fixed bin(63) on UNIX, as opposed to fixed bin(71) on Multics. The maximum precision of UNIX PL/I is 17 digits. A number greater than 17 digits (as is possible in the case of microseconds) will lose the precision of the least significant digits. Info Seg: udate_time_.i 03/11/91 17 Product Differences Guide Bull HN _________________________________________________________________ Command/Subroutine: udate_time_$format_max_length Function: This entry returns the length of the longest result which a format can generate. The zone and/or language in which to work may be specified. Syntax: declare udate_time_$format_max_length entry (char(*), char(*), char(*)) returns (fixed bin (15)); max_len = udate_time_$format_max_length (format, zone, lang); Multics Equivalent: date_time_$format_max_length Differences: none Info Seg: udate_time_.i _________________________________________________________________ Command/Subroutine: udate_time_$from_clock Function: Given a Multics standard calendar clock value and an output time zone name, returns the month, day of the month, the year, the hour of the day, the minute of the hour, the second of the minute, the number of microseconds, the day in week, the day in year, and the day in clock. The caller may specify one of the time zones in the time_info_ in which the decoded clock value is to be expressed, or may request that the value be expressed in one of the default time zones. Syntax: declare udate_time_$from_clock entry (fixed bin(63), char(*), ptr, fixed bin(31)); call udate_time_$from_clock_ (clock, zone, addr(time_value), code); Multics Equivalent: date_time_$from_clock Differences: The clock variable is fixed bin(63) on UNIX, as opposed to fixed bin(71) on Multics. The code parameter which holds the standard status code is changed from fixed bin(35) on Multics to fixed bin(31) on UNIX. Info Seg: udate_time_.i 18 03/11/91 Bull HN Product Differences Guide _________________________________________________________________ Command/Subroutine: udate_time_$from_clock_interval Function: Given two clock values, returns the number of years, months, weeks, days, hours, minutes, seconds, and microseconds between them. The set of units to use is specified, as well as whether any are to include the fractional remainder. Syntax: declare udate_time_$from_clock_interval entry (fixed bin(63), fixed bin(63), ptr, fixed bin(31)); call udate_time_$from_clock_interval (clock1, clock2, addr (time_offsets), code); Multics Equivalent: date_time_$from_clock_interval Differences: The clock1 and clock2 variable is fixed bin(63) on UNIX, as opposed to fixed bin(71) on Multics. The code parameter which holds the standard status code is changed from fixed bin(35) on Multics to fixed bin(31) on UNIX. Info Seg: udate_time_.i _________________________________________________________________ Command/Subroutine: udate_time_$fstime Function: This entry performs the same function as udate_time_ given a 36-bit storage system date value. Syntax: declare udate_time_$fstime entry (bit(36) aligned, char(*)); call udate_time_$fstime (ssclock, str); Multics Equivalent: date_time_$fstime Differences: none Info Seg: udate_time_.i 03/11/91 19 Product Differences Guide Bull HN _________________________________________________________________ Command/Subroutine: udate_time_$offset_to_clock Function: This entry point creates a new clock value by adjusting an input clock value to a specified day-of-week and then adding relative date/time offsets. The relative date/time values include a year offset, month offset, week offset, day offset, hour offset, minute offset, second offset, and microsecond offset. Any of these values may be zero (no offset from input clock value) or negative (backwards offset from input clock value). In addition, an input time zone is specified. Syntax: declare udate_time_$offset_to_clock entry (ptr, fixed bin(63), char(*), fixed bin(63), fixed bin(31)); call udate_time_$offset_to_clock (addr(time_offset), clock_in, zone, clock, code); Multics Equivalent: date_time_$offset_to_clock Differences: The clock_in and clock variable is fixed bin(63) on UNIX, as opposed to fixed bin(71) on Multics. The code parameter which holds the standard status code is changed from fixed bin(35) on Multics to fixed bin(31) on UNIX. Info Seg: udate_time_.i _________________________________________________________________ Command/Subroutine: udate_time_$set_lang Function: This entry sets or resets the user's default time language. Syntax: declare udate_time_$set_lang (char(*), fixed bin(31)); call udate_time_$set_lang (lang, code); Multics Equivalent: date_time_$set_lang Differences: The code parameter which holds the standard status code is changed from fixed bin(35) on Multics to fixed bin(31) on UNIX. Info Seg: udate_time_.i 20 03/11/91 Bull HN Product Differences Guide _________________________________________________________________ Command/Subroutine: udate_time_$set_zone Function: This entry sets or resets the user's default time zone. Syntax: declare udate_time_$set_zone (char(*), fixed bin(31)); call udate_time_$set_zone (lang, code); Multics Equivalent: date_time_$set_zone Differences: The code parameter which holds the standard status code is changed from fixed bin(35) on Multics to fixed bin(31) on UNIX. The system default time zone is controlled by the UNIX enviornment variable DTZ. If this enviornment variable is not set, then udate_time will stop execution when a reference to the system default time zone is made. Info Seg: udate_time_.i _________________________________________________________________ Command/Subroutine: udate_time_$to_clock Function: Given any or all of the following -- years, months, days, hours, minutes, seconds, microseconds, day in week, day in year, or day in clock -- returns a standard clock value which represents the encoding of these values. All the values must be valid, e.g. hours not greater than 23, etc. Syntax: declare udate_time_$to_clock (ptr, fixed bin(63), fixed bin(31)); call udate_time_$to_clock (addr (time_value), clock, code); Multics Equivalent: date_time_$to_clock Differences: The clock variable is fixed bin(63) on UNIX, as opposed to fixed bin(71) on Multics. The code parameter which holds the standard status code is changed from fixed bin(35) on Multics to fixed bin(31) on UNIX. Info Seg: udate_time_.i 03/11/91 21 Product Differences Guide Bull HN _________________________________________________________________ Command/Subroutine: udate_time_$valid_format Function: This entry checks the validity of a format string using precisely the same tests as udate_time_$format. Syntax: declare udate_time_$valid_format (char(*), fixed bin, fixed bin(31)); call udate_time_$valid_format (format, errloc, code); Multics Equivalent: date_time_$valid_format Differences: The code parameter which holds the standard status code is changed from fixed bin(35) on Multics to fixed bin(31) on UNIX. Info Seg: udate_time_.i _________________________________________________________________ Command/Subroutine: udecode_descriptor_ Function: extracts information from argument descriptors. Syntax: declare udecode_descriptor_ entry (ptr, fixed bin(15), fixed bin(15), bit(1) aligned, fixed bin(15), fixed bin(31), fixed bin(15)); call udecode_descriptor_ (ptr, n, type, packed, ndims, size, scale); Multics Equivalent: decode_descriptor_ Differences: udecode_descriptor_ does not decode argument descriptors for BASIC, COBOL, PASCAL or COBOL programs, because the Bull XPS UNIX implementations of these languages do not use the PL/1 argument descriptor format. Because there are no "old" argument descriptor formats on Bull XPS UNIX, udecode_descriptor_ does not check for them. The "size" parameter is fixed bin(31) instead of fixed bin(24). udecode_descriptor_ returns -1 for "type" if the "n" parameter is negative or if the "ptr" parameter is null. 22 03/11/91 Bull HN Product Differences Guide Info Seg: udecode_desc.i _________________________________________________________________ Command/Subroutine: uexpand_pathname_ Function: converts a relative or absolute pathname into a directory name and entryname. Syntax: declare uexpand_pathname_ entry (char(*), char(*), char(*), fixed bin (31)); call uexpand_pathname_ (pathname, dirname, entryname, code); Multics Equivalent: expand_pathname_ Differences: The code parameter which holds the standard status code is changed from fixed bin(35) on Multics to fixed bin(31) on UNIX. The maximum length for the absolute pathname has increased from 168 characters on Multics to 255 characters on the BULL XPS UNIX system. The entrypoints that deal with expansion of archive components -- expand_pathname_$component and expand_pathname_$component_add_suffix -- were not ported. An additional feature has been created to allow the use of UNIX pathname conventions. A change in the syntax of the pathname has been made: the substitution of ">" and "<" on Multics to "/" and "../" on BULL XPS UNIX. A number of successive forward slashes (/) is allowed. The string "./" is interpreted correctly to mean "stay in the current directory." And finally, the string "../" is interpreted correctly to mean "to specify the parent directory." (i.e. "/user/////mp//tools/path/../../././.../." will be returned as directory = "/user/mp/..." entry = ".") Finally, the code for the write-around for the obsolete expand_path_ has been omitted. Info Seg: uexp_path_.i 03/11/91 23 Product Differences Guide Bull HN _________________________________________________________________ Command/Subroutine: uexpand_pathname_$add_suffix Function: expands a relative or absolute pathname into a directory name and entryname portion, adding a suffix to the entryname if that suffix is not already present. Syntax: declare uexpand_pathname_$add_suffix entry (char(*), char(*), char(*), char(*), fixed bin (31)); call uexpand_pathname_$add_suffix (pathname, suffix, dirname, entryname, code); Multics Equivalent: expand_pathname_$add_suffix Differences: The code parameter which holds the standard status code is changed from fixed bin(35) on Multics to fixed bin(31) on UNIX. The maximum length for the absolute pathname has increased from 168 characters on Multics to 255 characters on the BULL XPS UNIX system. Info Seg: uexp_path_.i _________________________________________________________________ Command/Subroutine: uget_wdir_ Function: The uget_wdir_ function returns the absolute pathname of the user's current working directory. Syntax: declare uget_wdir_ entry returns (character (*)); working_dir = uget_wdir_ (); Multics Equivalent: uget_wdir_ Differences: The uget_wdir_ subroutine does not check to see if the working directory has been set for the current ring since rings do not exist on the BULL XPS UNIX system. A change has been made to accommodate the difference in the syntax of a pathname: the replacement of ">" on Multics for "/" on UNIX as entryname separators. 24 03/11/91 Bull HN Product Differences Guide If the absolute pathname of the user's current working directory exceeds 255 characters (instead of 168 characters on Multics), the upathname_ entrypoint returns an invalid pathname with the characters " ". This informs the reader that the pathname exceeds 255 characters. Info Seg: uget_wdir_.i _________________________________________________________________ Command/Subroutine: uioa_ Function: formats the input data according to a control string and writes the resulting string to standard output. A newline is appended to the result string. Syntax: declare uioa_ entry options (variable); call uioa_ (control_string, arg1, ..., argN); Multics Equivalent: ioa_ Differences: The entrypoints ioa_$switch, ioa_$switch_nnl, ioa_$stream, and ioa_$stream_nnl have been removed. The routines uioa_$fd and uioa_$fdnnl have been added. These routines are functionally equivalent to ioa_$switch/ioa_$stream and ioa_$switch_nnl/ioa_$stream_nnl respectively, except that the I/O switch argument must now be a file descriptor as defined in UNIX. All the control string codes that ioa_ accepts are supported by uioa_, and behave equivalently, except for the printing of machine dependent types. These types are 1) "^w", due to differences in the size of UNIX words and Multics words; and 2) "^p", due to differences in memory layout and pointers between UNIX and Multics. Info Files: uioa_.i, uioa_ctrl.g.i 03/11/91 25 Product Differences Guide Bull HN _________________________________________________________________ Command/Subroutine: uioa_$nnl Function: formats the input data according to the control string and writes the resulting string to standard output. A newline is not appended to the result string. Syntax: declare uioa_$nnl entry options (variable); call uioa_$nnl (control_string, arg1, ..., argN); Multics Equivalent: ioa_$nnl Differences: See differences for the uioa_ entrypoint. Info Files: uioa_.i, uioa_ctrl.g.i _________________________________________________________________ Command/Subroutine: uioa_$fd Function: Formats the input data according to the control string and writes the resulting string to a specified UNIX file descriptor. A newline is appended to the result string. Syntax: declare uioa_$fd entry options (variable); call uioa_$fd (file_desc, control_string, arg1, ..., argN); Multics Equivalent: Similar to ioa_$switch and ioa_$stream Differences: See differences for the uioa_ entrypoint. Info Files: uioa_.i, uioa_ctrl.g.i _________________________________________________________________ Command/Subroutine: uioa_$fdnnl Function: Formats the input data according to the control string and writes the resulting string to a specified UNIX file descriptor. A newline is not appended to the result string. 26 03/11/91 Bull HN Product Differences Guide Syntax: declare uioa_$fdnnl entry options (variable); call uioa_$fdnnl (file_desc, control_string, arg1, ..., argN); Multics Equivalent: Similar to ioa_$switch_nnl and ioa_$stream_nnl Differences: See differences for the uioa_ entrypoint. Info Files: uioa_.i, uioa_ctrl.g.i _________________________________________________________________ Command/Subroutine: uioa_$general_rs Function: This entrypoint is used to provide the uioa_ subroutine with a control string and format arguments taken from a previously created argument list to which a pointer has been obtained. Syntax: declare uioa_$general_rs entry (ptr, fixed bin(15), fixed bin(15), char(*), fixed bin(31), bit(1) aligned, bit(1) aligned); call uioa_$general_rs (arglist_ptr, cs_argno, ff_argno, ret_string, len, pad_sw, nl_sw); Multics Equivalent: ioa_$general_rs Differences: See differences for the uioa_ entrypoint. Info Files: uioa_.i, uioa_ctrl.g.i _________________________________________________________________ Command/Subroutine: uioa_$rs Function: Edits the resulting string as does the uioa_ entrypoint, but instead of being written to terminal output, the string is passed back to the caller. A newline character is appended to the end of the output string. The output string is also padded with spaces if it is non-varying. 03/11/91 27 Product Differences Guide Bull HN Syntax: declare uioa_$rs entry options (variable); call uioa_$rs (control_string, ret_string, len, arg1, ..., argN); Multics Equivalent: ioa_$rs Differences: See differences for the uioa_ entrypoint. Info Files: uioa_.i, uioa_.ctrl.g.i _________________________________________________________________ Command/Subroutine: uioa_$rsnnl Function: Edits the resulting string as does the uioa_ entrypoint, but instead of being written to terminal output, the string is passed back to the caller. A newline character is not appended to the end of the output string. The output string is also padded with spaces if it is non-varying. Syntax: declare uioa_$rsnnl entry options (variable); call uioa_$rsnnl (control_string, ret_string, len, arg1, ..., argN); Multics Equivalent: ioa_$rsnnl Differences: See differences for the uioa_ entrypoint. Info Files: uioa_.i, uioa_.ctrl.g.i _________________________________________________________________ Command/Subroutine: uioa_$rsnp Function: Edits the resulting string as does the uioa_ entrypoint, but instead of being written to terminal output, the string is passed back to the caller. A newline character is appended to the end of the returned output string. This string is not right-padded with spaces. Syntax: declare uioa_$rsnp entry options (variable); call uioa_$rsnp (control_string, ret_string, len, arg1, ..., argN); 28 03/11/91 Bull HN Product Differences Guide Multics Equivalent: ioa_$rsnp Differences: See differences for the uioa_ entrypoint. Info Files: uioa_.i, uioa_.ctrl.g.i _________________________________________________________________ Command/Subroutine: uioa_$rsnpnnl Function: Edits the resulting string as does the uioa_ entrypoint, but instead of being written to terminal output, the string is passed back to the caller. A newline character is not appended to the end of the returned output string. This string is not right-padded with spaces. Syntax: declare uioa_$rsnpnnl entry options (variable); call uioa_$rsnpnnl (control_string, ret_string, len, arg1, ..., argN); Multics Equivalent: ioa_$rsnpnnl Differences: See differences for the uioa_ entrypoint. Info Files: uioa_.i, uioa_.ctrl.g.i _________________________________________________________________ Command/Subroutine: ulex_error_ Function: generates compiler-style error messages on the UNIX standard error output (stderr) for translators generated by the rdc command, and for other procedures that process tokens generated by the ulex_string_ subroutine. Syntax: declare ulex_error_ entry options (variable); call ulex_error_ (error_number, Serror_printed, severity_no, max_severity_no, Pstmt, Ptoken, Scontrol, message, brief_message, arg1, ..., argN); Multics Equivalent: lex_error_ Differences: None. 03/11/91 29 Product Differences Guide Bull HN Info file: ulex_error_.i _________________________________________________________________ Command/Subroutine: ulex_string_ Function: parses an input string according to the delimiters, break characters, and control information given as its arguments. The input string consists of two parts: the first part is a set of characters which are to be ignored by the parser except for the counting of lines; the second part consists of the characters to be parsed. Syntax: declare ulex_string_$lex entry (ptr, fixed bin(31), fixed bin(31), ptr, bit(*), char(*), char(*), char(*), char(*), char(*), char(*) varying aligned, char(*) varying aligned, char(*) varying aligned, char(*) varying aligned, ptr, ptr, fixed bin(31)); call ulex_string_$lex entry (Pinput, Linput, Lignored_input, Psegment, Slex, quote_open, quote_close, comment_open, comment_close, statement_delim, break_chars, ignored_break_chars, lex_delims, lex_control_chars, Pfirst_stmt_desc, Pfirst_token_desc, code); Multics Equivalent: lex_string_ Differences: 1) "Linput" and "Lignored_input" arguments changed to fixed bin (31) on UNIX from fixed bin (21) on Multics. 2) "code" argument changed to fixed bin (31) on UNIX from fixed bin (35) on Multics. 3) The internal representation of the "lex_control_chars" argument has been changed from a 9-bit structure on Multics to a 16-bit structure on UNIX. The length of "lex_control_chars" should be doubled. Info file: ulex_string_.i 30 03/11/91 Bull HN Product Differences Guide _________________________________________________________________ Command/Subroutine: ulex_string_$init_lex_delims Function: constructs two character strings from the set of break characters and comment, quoting, and statement delimiters: one string contains the first character of every delimiter or break character defined by the language to be parsed; the second string contains a character of control information for each character in the first string. These two character strings form the break tables that the ulex_string_ subroutine uses to parse an input string. It is intended that these two (delimiter and control) character strings be internal static variables of the program that calls ulex_string_, and that they be initialized only once per process. They can then be used in successive calls to ulex_string_$lex. Syntax: declare ulex_string_$init_lex_delims entry (char(*), char(*), char(*), char(*), char(*), bit(*), char(*) varying aligned, char(*) varying aligned, char(*) varying aligned, char(*) varying aligned); call ulex_string_$init_lex_delims (quote_open, quote_close, comment_open, comment_close, statement_delim, Sinit, break_chars, ignored_break_chars, lex_delims, lex_control_chars); Multics Equivalent: lex_string_$init_lex_delims Differences: The internal representation of the "lex_control_chars" argument has been changed from a 9-bit structure on Multics to a 16-bit structure on UNIX. The length of "lex_control_chars" should be doubled. Info file: ulex_string_.i _________________________________________________________________ Command/Subroutine: uiox_ Function: The uiox_ subroutine library implements the Multics I/O system, as ported to the UNIX System V operating system. Details of the I/O system are given in the Multics to UNIX Migration Guide, and in the Multics Subroutines and I/O Modules manual (AG93). Multics Equivalent: iox_ 03/11/91 31 Product Differences Guide Bull HN Differences: See section 9. Info File: uiox_.i _________________________________________________________________ Command/Subroutine: uiox_$attach_loud Function: This entrypoint is the same as uiox_$attach_switch except that a call to this entrypoint turns on the error reporting switch of the I/O module. This means that the attach routine of the I/O module displays an error message when an error is detected, giving more information than is reported by the other attach entrypoints. Syntax: dcl uiox_$attach_loud entry (bit(32), char(*), fixed(31)); call uiox_$attach_loud (atel, attach_desc, code); Multics Equivalent: iox_$attach_loud Differences: The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). Info File: uiox_.i _________________________________________________________________ Command/Subroutine: uiox_$attach_name Function: Attaches an I/O switch in accordance with a specified attach description. The switch is designated by name and an ATEL for the switch is returned. The switch is created if it does not already exist. Syntax: dcl uiox_$attach_name entry (char(*), bit(32), char(*), fixed(31)); call uiox_$attach_name (switch_name, atel, attach_desc, code); Multics Equivalent: iox_$attach_name 32 03/11/91 Bull HN Product Differences Guide Differences: The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). Info File: uiox_.i _________________________________________________________________ Command/Subroutine: uiox_$attach_switch Function: Attaches an I/O switch in accordance with a specified attach description. The I/O module is located using the current search rules. Syntax: dcl uiox_$attach_switch entry (bit(32), char(*), fixed(31)); call uiox_$attach_switch (atel, attach_desc, code); Multics Equivalent: iox_$attach_switch Differences: The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). Info File: uiox_.i _________________________________________________________________ Command/Subroutine: uiox_$close Function: This entrypoint closes an I/O switch. Syntax: dcl uiox_$close entry (bit(32), fixed(31)); call uiox_$close (atel, code); Multics Equivalent: iox_$close Differences: The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). 03/11/91 33 Product Differences Guide Bull HN Info File: uiox_.i _________________________________________________________________ Command/Subroutine: uiox_$close_file Function: This entrypoint closes an I/O switch. If the switch is not open its state is not changed, and the code error_table_$not_open is returned. This entrypoint differs from the uiox_$close entrypoint due to the addition of the close description argument. For those I/O modules that support the close_file operation, the close description offers a means of providing file closing parameters such as a closing comment, where to position to upon closing, etc. Syntax: dcl uiox_$close_file entry (bit(32), char(*), fixed(31)); call uiox_$close_file (atel, cld, code); Multics Equivalent: iox_$close_file Differences: The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). Info File: uiox_.i _________________________________________________________________ Command/Subroutine: uiox_$control Function: This entrypoint performs a specified control order on an I/O switch. The allowed control orders depend on the attachment of the switch. For details on control orders, see the description of the particular I/O module used in the attach operation. Syntax: dcl uiox_$control entry (bit(32), char(*), ptr, fixed(31)); call uiox_$control (atel, order, info_ptr, code); Multics Equivalent: iox_$control 34 03/11/91 Bull HN Product Differences Guide Differences: The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). Info File: uiox_.i _________________________________________________________________ Command/Subroutine: uiox_$delete_record Function: This entrypoint deletes the current record from the file (to which an I/O switch is attached). The switch must be open for sequential_update, keyed_sequential_update, or direct_update. If the file is open for direct_update and the deletion takes place, the current and next record positions are set to null. For keyed_sequential_update, the current and next record positions are set to the record following the deleted record or (if there is no such record) to end of file. Syntax: dcl uiox_$delete_record entry (bit(32), fixed(31)); call uiox_$delete_record (atel, code) Multics Equivalent: iox_$delete_record Differences: The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). Info File: uiox_.i _________________________________________________________________ Command/Subroutine: uiox_$destroy_switch Function: This entrypoint frees the storage used for an I/O switch. The switch must be in the detached state. Any existing ATELs for this switch become invalid. Syntax: dcl uiox_$destroy_switch entry (bit(32), fixed(31)); call uiox_$destroy_switch (atel, code); 03/11/91 35 Product Differences Guide Bull HN Multics Equivalent: iox_$destroy_iocb Differences: The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). Info File: uiox_.i _________________________________________________________________ Command/Subroutine: uiox_$detach Function: This entrypoint detaches an I/O switch. It differs from uiox_$detach_switch in that it provides an additional argument -- a detach description (dtd). Syntax: dcl uiox_$detach entry (bit(32), char(*), fixed(31)); call uiox_$detach (atel, dtd, code); Multics Equivalent: iox_$detach Differences: The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). Info File: uiox_.i _________________________________________________________________ Command/Subroutine: uiox_$detach_switch Function: This entrypoint detaches an I/O switch. Syntax: dcl uiox_$detach_switch entry (bit(32), fixed(31)); call uiox_$detach_switch (atel, code); Multics Equivalent: iox_$detach_iocb Differences: The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). 36 03/11/91 Bull HN Product Differences Guide Info File: uiox_.i _________________________________________________________________ Command/Subroutine: uiox_$find_switch Function: This entrypoint returns an ATEL for the named I/O switch. The ATE is created if it does not already exist. If the switch you need is for one of the four standard I/O switches, you do not need uiox_$find_switch, but should use one of the four standard external static variables uiox_$user_io, uiox_$user_input, uiox_$user_output, or uiox_$error_output. Syntax: dcl uiox_$find_switch entry (char(*), bit(32), fixed(31)); call uiox_$find_switch (switch_name, atel, code); Multics Equivalent: iox_$find_iocb Differences: The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). Info File: uiox_.i _________________________________________________________________ Command/Subroutine: uiox_$get_chars Function: This entrypoint reads 8-bit bytes from the unstructured file or device to which an I/O switch is attached. The switch must be open for stream_input or stream_input_output. The desired number of bytes, n, is specified in the call. Some I/O modules may actually read fewer than n bytes into the buffer, even though n bytes are available from the file or device. The contents of the buffer beyond the last byte read are undefined. If the switch is attached to a file, bytes are read beginning with the next byte, and the next byte position designator is advanced by the number of bytes read. 03/11/91 37 Product Differences Guide Bull HN Syntax: dcl uiox_$get_chars entry (bit(32), ptr, fixed(31), fixed(31),fixed(31)); call uiox_$get_chars (atel, buf_p, buf_l, n_read, code); Multics Equivalent: iox_$get_chars Differences: The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). The buf_p and n_read have been changed from fixed bin (21) on Multics to fixed bin (31) on UNIX. Info File: uiox_.i _________________________________________________________________ Command/Subroutine: uiox_$get_line Function: This entrypoint reads 8-bit bytes from the unstructured file or device to which an I/O switch is attached. The switch must be open for stream_input or stream_input_output. Bytes are read until the input buffer is filled, a newline character is read, or end of file is reached -- whichever occurs first. The contents of the buffer beyond the last byte read are undefined. If the switch is attached to a file, bytes are read beginning with the next byte, and the next byte position designator is advanced by the number of bytes read. Syntax: dcl uiox_$get_line entry (bit(32), ptr, fixed(31), fixed(31), fixed(31)); call uiox_$get_line (atel, buf_p, buf_l, n_read, code); Multics Equivalent: iox_$get_line Differences: The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). The buf_p and n_read have been changed from fixed bin (21) on Multics to fixed bin (31) on UNIX. Info File: uiox_.i 38 03/11/91 Bull HN Product Differences Guide _________________________________________________________________ Command/Subroutine: uiox_$list_switches Function: This routine returns a list of switch names and ATELs for all switches in the Attach Table. The list is described by the declaration, found in include file uiox_at_dcls.i The list is allocated in the user's heap, and must be freed by the user. The storage is local to the UNIX process requesting the list. Syntax: dcl uiox_$list_switches entry (ptr, fixed(15), fixed(31)); call uiox_$list_switches (list_p, switch_count, code); Multics Equivalent: none Differences: NA Info File: uiox_.i _________________________________________________________________ Command/Subroutine: uiox_$look_switch Function: This entrypoint returns an ATEL for a named I/O switch. If the ATE does not exist, it is not created, and a zero value and the code error_table_$no_switch are returned. Syntax: dcl uiox_$look_switch entry (char(*), bit(32) ,fixed(31)); call uiox_$look_switch (switch_name, atel, code); Multics Equivalent: iox_$look_iocb Differences: The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). Info File: uiox_.i 03/11/91 39 Product Differences Guide Bull HN _________________________________________________________________ Command/Subroutine: uiox_$modes Function: This entrypoint is used to obtain or set modes that affect the subsequent behavior of an I/O switch. The switch must be attached via an I/O module that supports modes. Each mode is a sequence of nonblank characters. A mode string is a sequence of modes, separated by commas and containing no blanks. For a list of valid modes, see the particular I/O module involved. Syntax: dcl uiox_$modes entry (bit(32), char(*), char(*), fixed(31)); call uiox_$modes (atel, new_modes, old_modes, code); Multics Equivalent: iox_$modes Differences: The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). Info File: uiox_.i _________________________________________________________________ Command/Subroutine: uiox_$move_attach Function: This entrypoint moves an attachment from one I/O switch, s1, to another I/O switch, s2. The s1 I/O switch must be in the attached state and the s2 switch must be in the detached state when the entry point is called. Moving the attachment moves the attach description and open description of the s1 I/O switch to the s2 I/O switch. All information is moved from the ATE of the s1 I/O switch to the ATE of the s2 I/O switch. Attach and open data blocks maintained by the I/O module (if the s1 I/O switch is attached) are not affected. Finally, the s1 I/O switch is set to the detached state. Syntax: dcl uiox_$move_attach entry (bit(32), bit(32), fixed(31)); call uiox_$move_attach (atel_1, atel_2, code); Multics Equivalent: iox_$move_attach 40 03/11/91 Bull HN Product Differences Guide Differences: The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). Info File: uiox_.i _________________________________________________________________ Command/Subroutine: uiox_$open Function: This entrypoint opens an I/O switch. The switch must be attached via an I/O module that supports the specified opening mode, and it must be in the closed state. If the switch is attached to a file, the appropriate file position designators are established, and an existing file may be replaced by an empty file. This replacement may be avoided by specifying extension of the file in the attach description. Syntax: dcl uiox_$open entry (bit(32), fixed(15), fixed(31)); call uiox_$open (atel, mode, code); Multics Equivalent: iox_$open Differences: The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). The unused field has been removed from the parameter list. The mode has been changed from fixed bin on Multics to fixed bin (15) on UNIX. Info File: uiox_.i _________________________________________________________________ Command/Subroutine: uiox_$open_file Function: This entrypoint opens an I/O switch. The switch must be attached via an I/O module that supports the specified opening mode, and it must be in the closed state. If the switch is not attached, its state is not changed, and the code error_table_$not_attached is returned. If the switch is already open, the code error_table_$not_closed is returned. 03/11/91 41 Product Differences Guide Bull HN This entrypoint differs from the uiox_$open entrypoint due to the addition of the open description argument. For those I/O modules that support the open_file operation, the open description offers a means of providing file opening parameters such as format, block size, record size, etc. The open description also allows the logical separation of attachment of resources, such as tape volumes, with the uiox_$attach_name and uiox_$attach_switch entrypoints, and file specific operations for those I/O modules that deal with multi-file resources. Syntax: dcl uiox_$open_file entry (bit(32), fixed(15), char(*), fixed(31)); call uiox_$open_file (atel, mode, opd, code); Multics Equivalent: iox_$open_file Differences: The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). The unused field has been removed from the parameter list. The mode has been changed from fixed bin on Multics to fixed bin (15) on UNIX. Info File: uiox_.i _________________________________________________________________ Command/Subroutine: uiox_$position Function: For an I/O switch attached to a file, this entrypoint positions to the beginning or end of the file, or skips forward or backward over a specified number of lines (unstructured files) or records (structured files). For an I/O switch attached to a device, this operation reads and discards characters until a specified number of newline characters have been skipped. The switch must be opened in one of the following modes: stream_input stream_input_output sequential_input sequential_input_output sequential_update keyed_sequential_input keyed_sequential_update In addition, for keyed openings, the next record position should not be null. If it is null, the code error_table_$no_record is returned. 42 03/11/91 Bull HN Product Differences Guide Syntax: dcl uiox_$position entry (bit(32), fixed(15), fixed(31), fixed(31)); call uiox_$position (atel, type, pos, code); Multics Equivalent: iox_$position Differences: The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). The type parameter has been changed from fixed bin on Multics to fixed bin (15) on UNIX. The pos parameter has been changed from fixed bin (21) on Multics to fixed bin (31) on UNIX. The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. Info File: uiox_.i _________________________________________________________________ Command/Subroutine: uiox_$put_chars Function: This entrypoint writes a specified number of 8-bit bytes to the unstructured file or device to which an I/O switch is attached. The switch must be open for stream_output or stream_input_output. In the case of a file, if the opening is for stream_output, the bytes are simply added at the end of the file. However, if the opening is for stream_input_output, and the next byte position is not at end of file, the file is first truncated so that the byte preceding the next byte becomes the last byte in the file. The bytes being written are then added at the end of the file, and the next byte position is set to end of file. Truncation can be suppressed in storage system files by specifying an appropriate attach option. See the description of the vfile_ I/O module for details. Syntax: dcl uiox_$put_chars entry (bit(32), ptr, fixed(31), fixed(31)); call uiox_$put_chars (atel, buf_p, buf_l, code); Multics Equivalent: iox_$put_chars Differences: The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). The buf_l parameter has been changed from fixed bin (21) on Multics to fixed bin (31) on UNIX. The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. 03/11/91 43 Product Differences Guide Bull HN Info File: uiox_.i _________________________________________________________________ Command/Subroutine: uiox_$read_key Function: This entrypoint returns both the key and length of the next record in an indexed file attached to an I/O switch. The switch must be open for keyed_sequential_input or keyed_sequential_update. The next record position is unchanged and the current record position is set to the next record if the operation is successful; otherwise, the current record position is set to null. Syntax: dcl uiox_$read_key entry (bit(32), char(*) var, fixed(31), fixed(31)); call uiox_$read_key (atel, key, rec_len, code); Multics Equivalent: iox_$read_key Differences: The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). The parameter rec_len has been changed from fixed bin (21) on Multics to fixed bin (31) on UNIX. The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. Info File: uiox_.i _________________________________________________________________ Command/Subroutine: uiox_$read_length Function: This entrypoint returns the length of the next record in a structured file attached to an I/O switch. The switch must be opened in one of the following modes: sequential_input sequential_input_output sequential_update keyed_sequential_input keyed_sequential_update direct_input direct_update 44 03/11/91 Bull HN Product Differences Guide The next record position is unchanged and the current record position is set to the next record if the operation is successful; otherwise, the current record position is set to null. Syntax: dcl uiox_$read_length entry (bit(32), fixed(31), fixed(31)); call uiox_$read_length (atel, rec_len, code); Multics Equivalent: iox_$read_length Differences: The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). The parameter rec_len has been changed from fixed bin (21) on Multics to fixed bin (31) on UNIX. The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. Info File: uiox_.i _________________________________________________________________ Command/Subroutine: uiox_$read_record Function: This entrypoint reads the next record in a structured file to which an I/O switch is attached. The switch must be opened in one of the following modes: sequential_input sequential_input_output sequential_update keyed_sequential_input keyed_sequential_update direct_input direct_update The read is successful if the next record position is at a record. In sequential and keyed_sequential openings, a successful read advances the next record position by one record; an unsuccessful read leaves it at the end of file or null. In direct openings, this operation always sets the next record position to null. In openings for update, a successful read sets the current record position to the record just read; an unsuccessful read sets it to null. In openings for keyed_sequential_update and direct_update, the key for insertion is always set to null. 03/11/91 45 Product Differences Guide Bull HN Syntax: dcl uiox_$read_record entry (bit(32), ptr, fixed(31), fixed(31), fixed(31)); call uiox_$read_record (atel, buf_p, buf_l, rec_len, code); Multics Equivalent: iox_$read_record Differences: The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). The parameters buf_l and rec_len have been changed from fixed bin (21) on Multics to fixed bin (31) on UNIX. The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. Info File: uiox_.i _________________________________________________________________ Command/Subroutine: uiox_$rewrite_record Function: This entrypoint replaces the current record in a structured file to which an I/O switch is attached. The switch must be open for sequential_update, keyed_sequential_update, or direct_update. For keyed_sequential_update and sequential_update, this operation sets the next record position to the record immediately following the current record or to end of file (if no such record exists). (It is possible that the next record position may already be at this point). For direct_update, the next record position is set to null. No other changes are made to the position designators. Syntax: dcl uiox_$rewrite_record entry (bit(32), ptr, fixed(31), fixed(31)); call uiox_$rewrite_record (atel, buf_p, rec_len, code); Multics Equivalent: iox_$rewrite_record Differences: The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). The parameter rec_len has been changed from fixed bin (21) on Multics to fixed bin (31) on UNIX. The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. Info File: uiox_.i 46 03/11/91 Bull HN Product Differences Guide _________________________________________________________________ Command/Subroutine: uiox_$seek_key Function: This entrypoint searches for a record with a given key in an indexed file to which an I/O switch is attached. It also serves to define the key for a record to be added by a following uiox_$write_record operation. The switch must be opened in one of the following modes: keyed_sequential_input keyed_sequential_output keyed_sequential_update direct_input direct_output direct_update Syntax: dcl uiox_$seek_key entry (bit(32), char(*) var, fixed(31), fixed(31)); uiox_$seek_key (atel, key, rec_len, code); Multics Equivalent: iox_$seek_key Differences: The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). The parameter rec_len has been changed from fixed bin (21) on Multics to fixed bin (31) on UNIX. The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. Info File: uiox_.i _________________________________________________________________ Command/Subroutine: uiox_$switch_data Function: This entrypoint is used to extract data from the Attach Table for the specified switch. The extracted data is returned in a structure described by the declaration located in uiox_at_dcls.i Syntax: dcl uiox_$switch_data entry (bit(32), ptr, fixed(31)); call uiox_$switch_data (atel, info_p, code); Multics Equivalent: none 03/11/91 47 Product Differences Guide Bull HN Differences: NA Info File: uiox_.i _________________________________________________________________ Command/Subroutine: uiox_$write_record Function: This entrypoint adds a record to a structured file to which an I/O switch is attached. The switch must be opened in one of the following modes: sequential_output sequential_update sequential_input_output keyed_sequential_output keyed_sequential_update direct_output direct_update Syntax: dcl uiox_$write_record entry (bit(32), ptr, fixed(31), fixed(31)); call uiox_$write_record (atel, buf_p, rec_len, code); Multics Equivalent: iox_$write_record Differences: The Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)). The parameter rec_len has been changed from fixed bin (21) on Multics to fixed bin (31) on UNIX. The error code is changed from fixed bin (35) on Multics to fixed bin (31) on UNIX. Info File: uiox_.i _________________________________________________________________ Command/Subroutine: upathname_ Function: given a directory name and an entry name, returns the pathname of the entry. Syntax: declare upathname_ entry (char (*), char (*)) returns (char (*)); path = upathname_ (dirname, entryname); 48 03/11/91 Bull HN Product Differences Guide Multics Equivalent: upathname_ Differences: A change has been made to accommodate the difference in the syntax of a pathname: the replacement of ">" on Multics for "/" on UNIX as entryname separators. If the pathname and the entryname combined exceed 255 characters (instead of 168 characters on Multics), the upathname_ entrypoint creates an invalid pathname with the characters " " in the last 20 characters of the path. This informs the reader that truncation occurred. Info File: upathname_.i _________________________________________________________________ Command/Subroutine: vfile_ Function: vfile_ is an I/O module supporting I/O from/to files in the UNIX storage system . Unstructured, Sequential, and Indexed/Sequential file types are supported. The vfile_ I/O module is not invoked directly, but via the uiox_ I/O system. Multics Equivalent: vfile_ Differences: See section 10. Info Seg: vfile_.i 03/11/91 49 Product Differences Guide Bull HN 3. _C_D_O _D_I_F_F_E_R_E_N_C_E_S 3.1. _S_u_m_m_a_r_y The UNIX cdo command is functionally equivalent to the Multics create_data_segment (cds) command. However, the source file format is different, and different suffixes are used for the source and output files. 3.2. _F_i_l_e_n_a_m_e_s The suffixes of source and output filenames used by UNIX cdo differ slightly from those used by Multics cds: Multics cds UNIX cdo ___________ ________ source.cds source.d output output.o 3.3. _C_o_n_t_r_o_l _A_r_g_u_m_e_n_t_s UNIX cdo has a control argument not present in Multics cds: -pl1_args arguments specifies a list of control arguments to be passed to the pl1 compiler. If given, this control argument must appear last on the command line. 3.4. _S_o_u_r_c_e _F_i_l_e _F_o_r_m_a_t The format of source files used by UNIX cdo differs considerably from that of the source files used by Multics cds. The Multics cds command uses the PL/I symbol table to get information on entry names and lengths for the data structure. UNIX cdo relies on a call to the create_data_object_ procedure from within the source file to provide this information, as well as the name of the data item, the section it is to be located in, and the address of the data it is to be initialized with. 50 03/11/91 Bull HN Product Differences Guide A cdo source file is made by including cdo_item.i and declaring an array of cdo_items in the cdo source file as follows: example: proc () options (main); %include cdo_item; dcl N_DATA_ITEMS fixed bin int static options (constant) init (1); dcl create_data_object_ entry (char (*), ptr, fixed bin, fixed bin (31)); dcl 01 item_array (N_DATA_ITEMS) like cdo_item; dcl version fixed bin (31); This array is then filled out with the relevant information for each external variable or constant: item_array (1).ep = "version"; /* name of the variable */ item_array (1).constant = "1"b ; /* this is set to "1"b */ /* if the item resides in*/ /* the text and if "0"b */ /* in the static section */ item_array (1).datal = size (version); /* length of the storage */ /* in 16 bit words */ version = 112; /* initial value of the */ /* external variable */ item_array (1).datap = addr (version); /* address of the data */ create_data_object_ is called to create the UNIX object file. The parameters are the name of the object file to be created (the ".o" suffix will be supplied by create_data_object_), a pointer to the "item_array", the number of items in the item array, and the error code returned by create_data_object_. call create_data_object_ ("cdo_test", addr (item_array), N_DATA_ITEMS, ec); After cdo is run on the cdo source file, the resulting object file can be linked with other programs which access the declared external variables or constants. For information on linking, see the UNIX "pl1", "cc" and "ld" commands. Users are recommended to use the "pl1" command for linking "pl1" and "cdo" objects. 03/11/91 51 Product Differences Guide Bull HN 4. _C_E_T _D_I_F_F_E_R_E_N_C_E_S 4.1. _S_u_m_m_a_r_y Multics has a facility that allows developers to generalize error references and error messages. This facility is known as an error table. The error table originates as an ALM program that assembles into an externally accessible table of error codes that is referenced by external variable names. The UNIX implementation of cet is functionally equivalent to the error table facility provided by the Multics assembler. This command translates ALM error table source files into UNIX object files. 4.2. _C_o_n_t_r_o_l _a_r_g_u_m_e_n_t_s The UNIX cet command supports one control argument: -blocking_factor N, -bf N The -blocking_factor argument specifies how many error table entries are to be placed into the created error table file. If the original source file contains more than the specified value of error table entries, cet will create multiple error table files each containing N entries. The -blocking_factor argument may not be used with the system error table. If the -blocking_factor option is given, the resulting error table files will be named using the format below: source_name||file_number||".o" source_name is the source name specified in the source file, truncated to 9 characters. This restriction may exist only on the XPS-UNIX system. file_number is a number assigned to the file by cet, starting at 1 and continuing to the maximum number of files required to create the error table files. (Maximum 999). ".o" is the standard object suffix on UNIX. 52 03/11/91 Bull HN Product Differences Guide The resulting error table files can then be archived. If the archive is specified as a library to the UNIX load command, only those files required by a specific object will be loaded. 4.3. _F_i_l_e_n_a_m_e_s The suffixes of the source and output files differ: Multics cet UNIX cet ___________ ________ source.alm source.e output output.o output.m UNIX cet may create two output files. The file with the ".o" suffix is an object file corresponding the the UNIX common object file format (COFF). This file will contain two entry points for each error table entry: error_table_$error_entry (identical to a Multics entry name) error_table_error_entry (no "$") The second entry name allows access by the UNIX assembler and the "C" language. This ".o" output file is always created. The output file with the ".m" suffix contains the text of the error message. This is generated only for the system error table, and allows error messages to be passed between processes on UNIX. 03/11/91 53 Product Differences Guide Bull HN 5. _H_E_L_P _D_I_F_F_E_R_E_N_C_E_S Although UNIX-Help and Multics-Help are virtually identical, there remain a number of small differences caused by operating system dependencies. This info file describes the differences between the UNIX and Multics help facilities. A primary difference is that UNIX-Help is implemented in the 'C' language, whereas Multics-Help is implemented in PL/I. This difference is assumed in all help related documentation and no further mention of it will be made. 5.1. _N_a_m_i_n_g _C_o_n_v_e_n_t_i_o_n_s UNIX restricts the length of filenames to 14 characters, as opposed to 32 characters on Multics. The "." character is treated as any other character except when it is the first character in the filename (signifying "hidden" characteristics). These differences are important when converting Multics info_seg names to UNIX info file names. Multics makes full use of a lengthy filename size to allow the user to create descriptive names. When copying info_segs from Multics to UNIX, name conversions will have to be performed. To reduce the number of characters required for the "suffixes" of a name, the Multics suffixes should be renamed (".i" is the standard UNIX suffix for info files) as follows: Multics UNIX ------- ---- .info .i .gi.info .g.i .changes.info .c.i A shortcoming of UNIX is that it is incapable of supporting multiple names (add_names) on a file as Multics does. Add_names are simulated on UNIX by creating multiple links to the source file where each link represents an add_name to the actual source. 54 03/11/91 Bull HN Product Differences Guide 5.2. _S_y_s_t_e_m _I_n_f_o _F_i_l_e_s The UNIX-Help facility, unlike Multics-Help, is not part of a standard release. Therefore, it is up to the installer to place the help facility where it seems appropriate. This will cause problems for the user when he establishes the HELP_PATH environment variable (see section "Notes on search paths"). To find where the help facility's info files have been installed, enter the command > help -header This will display the location of the info file "help.g.i". The remainder of the system info files will be located in the directory which contains help.g.i. 5.3. _S_e_a_r_c_h _P_a_t_h_s UNIX handles search_paths somewhat differently than does Multics. UNIX makes use of items called environment variables which can be used by applications to find out certain information about the process. These variables can contain any type of character information depending on how the application wants to use the variable. On Multics, however, these "variables" are very structured and only certain information is allowed within the variable (such as search_path information). The user defined environment variable HELP_PATH is used by the UNIX help facility to locate info files on the system. If HELP_PATH is not defined, then help will use a default path defined when the facility is installed on the system. If HELP_PATH is defined, then only the paths described in the variable will be used to locate info files. The user must describe the path of the system info files in the HELP_PATH variable in addition to other paths that are wanted. When help looks for info files, the paths in the HELP_PATH variable are searched in the order that they are defined. Other paths which the user may wish to have searched may be added to the contents of the HELP_PATH environment variable. This can be done through the UNIX command > setenv HELP_PATH path1:path2:pathN For further information on the setenv UNIX command, consult your UNIX system manuals. 03/11/91 55 Product Differences Guide Bull HN 5.4. _S_p_e_c_i_a_l _C_h_a_r_a_c_t_e_r_s UNIX, like Multics, performs a considerable amount of command line processing. However, UNIX's special characters (meta characters) are quite different than those on Multics. Two such conflicts that apply to this help facility are the star (*) and dollar ($) characters. UNIX does not support starnames in the same manner as Multics. That is, starnames are processed by UNIX's command shell as opposed to being passed in as arguments to the command on Multics. (Multics' system routines such as hcs_$star_ routine are then used to process the starnames.) On UNIX, the command > help * is the equivalent of Multics' > help [entries **] This means that when the user enters a starname on the command line to any of the new UNIX help commands, the shell will attempt to match and expand the starname BEFORE the command gets control. Because of this pre-processing by the commands shell, and the lack of system support, UNIX help does not perform internal starname matching. The command shell will pre-process the starnames in the context of the command. The "$" character presents another problem with UNIX. On Multics, this character is not special to the command and abbreviation processors, and is used to represent executable entrypoints within an executable segment. This allows the user to execute things like "foo_$bar" and "foo_$blat" from command level. On UNIX, however, the "$" character has special meaning to the command shell. It is pre-processed by the shell causing the character string following the "$" to be treated as a shell variable, replacing the variable on the command line with the contents of that variable. UNIX help handles the "$" character the same way that Multics help does (when help actually gets the character). However, to get the "$" character to help, it will be up to the user to enter the command (with the special characters) using single quotes ('). 56 03/11/91 Bull HN Product Differences Guide For example, the commands on UNIX > help 'cu_$arg_list_ptr' > help cu_ -ep arg_list_ptr are equivalent to Multics' > help cu_$arg_list_ptr 5.5. _P_r_o_g_r_a_m _L_i_b_r_a_r_i_e_s There are two program libraries associated with the help facility: librq.a, and libsp.a. They contain programming interface routines which are required by help and are made general to all uses. As with the location of the system info files, the location of these program libraries (and necessary header files for program development) is up to the system installer. Consult your site administrator to locate these utilities. librq.a contains functions to provide a request loop interface for an application. Multics implements this capability through subsystem utility entrypoints contained in "ssu_". The UNIX version does not attempt to mirror ssu_. The librq.a functions provide the necessary support required by UNIX-Help. For further information on the appropriate program interface routines, consult the system info files rq_error.i and rq_loop.i. libsp.a contains functions for UNIX search paths. As with the request loop utilities, no attempt was made to mirror Multics' search_path utilities. The libsp.a functions provide the necessary support required by UNIX-Help. For further information on the appropriate program interface routines, consult the system info files sp_error.i, sp_getpaths.i, sp_parse.i, and sp_verify.i. 03/11/91 57 Product Differences Guide Bull HN 6. _P_L_1 _C_O_M_M_A_N_D _D_I_F_F_E_R_E_N_C_E_S 6.1. _S_u_m_m_a_r_y The UNIX pl1 command is provided to allow the compilation of UNIX PL/I source files. The command is not identical to the Multics pl1 command; in particular, the source and include file suffixes, the creation of the object file, and some of the control arguments differ from the corresponding features of the Multics pl1 command. In addition, the UNIX implementation of the PL/I language is not identical to the Multics implementation. For more information, see the section "PL/I Language Differences" below. 6.2. _D_i_f_f_e_r_e_n_c_e_s _i_n _A_r_g_u_m_e_n_t_s The UNIX pl1 command accepts most of the Multics pl1 arguments. As well, it accepts multiple source filenames with different suffixes (see "Differences in Filenames", below). 6.3. _D_i_f_f_e_r_e_n_c_e_s _i_n _C_o_n_t_r_o_l _A_r_g_u_m_e_n_t_s The UNIX pl1 command has a number of control arguments not supported by the Multics command: -environment, -env displays the compilation environment (version date of migration package, path of migration compilers, include search paths, path of default libraries, locations of C compiler, assembler, rm command, mustrun command, error table and error message table). -extended_errors, -xerr causes unused variables, undeclared identifiers, and variables referenced in global scope to be reported as low-severity errors. 58 03/11/91 Bull HN Product Differences Guide -no_extended_errors, -nxerr causes reporting of unused variables, undeclared builtins and variables referenced in global scope to be suppressed. (Default) -include_dir path, -id path specifies the pathname of a directory which will be searched first when the compiler looks for an include file. -library path, -lb path specifies the pathname of a directory to be searched when looking for a subroutine library. This argument may be given more than once to specify all such directories that are needed. These directories will be searched before the system directories. If this argument is not given, only the system directories will be searched. -library_dir path, -ld path specifies the pathname of a library directory to be searched before the system libraries are searched. This argument may be given more than once to specify all library directories that are needed. If this argument is not given, only the system library directories are used. -no_link, -nlk creates one or more object files with ".o" suffixes, but does not link them with library routines to create an executable file. -no_quick_blocks, -nqb causes all internal procedures and begin blocks to have their own stack frames. This allows the UNIX "sdb" debugger to display a full stack trace (quick blocks are invisible to sdb). -quick_blocks, -qb causes the stack frame of a parent procedure or begin block to be used as the stack frame for internal procedures and begin blocks, whenever possible. (Default) -mustrun value, -mr value determines which processor the executable file will be run on when it is invoked. Allowable values are `0' (processor 0), `1' (processor 1) and `a' (any processor, the default). -output_file path, -of path, -o path Specifies the pathname of the output object file. Default is "a.out". 03/11/91 59 Product Differences Guide Bull HN -pl1_db causes debugging information about the pl1 command to be printed. This argument should normally be used only by compiler maintenance personnel. -verbose, -vb prints the compiler version number and messages at each stage of compilation -no_verbose, -nvb supresses printing of verbose compilation messages. (Default) The following Multics pl1 control arguments are not supported by UNIX pl1: -brief -check_ansi -long -long_profile -map -no_check_ansi -no_profile -no_separate_static -profile -separate_static -single_symbol_list 6.4. _D_i_f_f_e_r_e_n_c_e_s _i_n _F_i_l_e_n_a_m_e_s The suffixes of source and include files accepted by UNIX pl1 differ from those accepted by Multics pl1, as illustrated below: Multics pl1 UNIX pl1 ___________ ________ source.pl1 source.p source.d source.e source.c source.o source.s include.incl.pl1 include.i The ".p" suffix - used for most pl1 source files. The ".e" suffix - used for UNIX cet source files. The ".d" suffix - used for UNIX cdo source files. The ".o" suffix - used for non-executable object files which pl1 will link together to form an executable object file. The ".c" suffix - used for C language source files. The ".s" suffix - used for UNIX assembler source files. 60 03/11/91 Bull HN Product Differences Guide Additionally, the UNIX shell allows star names and other metacharacters in filenames. For example, the command pl1 *.p would compile all source files with a ".p" suffix in the current directory. For more information on UNIX metacharacters, see the documentation for the "csh" command in the UNIX manuals. 6.5. _C_r_e_a_t_i_o_n _o_f _O_b_j_e_c_t _F_i_l_e_s The UNIX pl1 command does not create an executable object file directly. Instead, it processes each of the source files, producing object files (with ".o" suffixes) which are then linked in with other ".o" suffixed library files containing the library routines referenced in the source files. The result of this linkage is an executable object file. The intermediate object files are automatically deleted. Object files produced by UNIX pl1 conform to the UNIX common object file format (COFF). 03/11/91 61 Product Differences Guide Bull HN 7. _P_L_/_I _L_A_N_G_U_A_G_E _D_I_F_F_E_R_E_N_C_E_S This section describes the differences between the Multics and UNIX implementations of the PL/I language. Note that it discusses differences only: if a feature is not described, it is assumed to be supported on the Bull HN UNIX compiler and will behave the same as it would in Multics PL/I. For information on the Multics implementation of PL/I, see the "Multics PL/I Language Specification" (AG94) and the "Multics PL/I Reference Manual (AM83). 7.1. _S_u_m_m_a_r_y The UNIX implementation of the PL/I language corresponds as closely as possible to Multics PL/I. Hardware differences have required some features to be dropped or modified. Some new features have been added as well. 7.2. _D_a_t_a _T_y_p_e_s Although UNIX PL/I supports all of the data types available in Multics PL/I, the maximum size and implementation of a given data type is often different. BASIC HARDWARE SIZES The UNIX PL/I compiler supports 8-bit characters and 16-bit words. 62 03/11/91 Bull HN Product Differences Guide COMPARISON OF DATA TYPE SIZES The following two tables compare the precision ranges and default precisions of data types on Multics and UNIX PL/I: PL/I Types: PL/I Data Type Multics precision UNIX precision _________________________________________________________ fixed bin 1 - 71 1 - 63 float bin 1 - 63 1 - 64 fixed dec 1 - 59 1 - 17 float dec 1 - 59 1 - 17 char 1 - 4*2**18 1 - 2**31 bit 1 - 36*2**18 1 - 2**31 Default differences: PL/I Data Type Multics precision UNIX precision _________________________________________________________ fixed bin 17 15 float bin 27 23 fixed dec 7 7 float dec 10 10 char 1 1 bit 1 1 DATA TYPE DEFINITIONS Definitions of the above data types are as follows: Fixed binary data type The fixed binary data type can have any precision between 1 and 63, inclusive. Aligned, unaligned, signed and unsigned values are supported. Aligned fixed binary values are aligned on word (16 bit) boundaries. Unaligned fixed binary values can be 03/11/91 63 Product Differences Guide Bull HN aligned on any bit boundary. Aligned fixed binary values with precisions from 1 to 15 take up one word of storage. Aligned values with precisions between 16 and 31 take up two words of storage (32 bits). Aligned values with precisions between 32 and 63 bits take up four words of storage (64 bits). The default precision is 15. Float binary data type The float binary data type can have any precision between 1 and 64, inclusive. Both aligned and unaligned values are supported. Aligned values are allocated on word (16 bit) boundaries. Unaligned values can start on any bit boundary. Aligned float binary values with precisions from 1 to 23 take up two words of storage (32 bits) and can have any value between -1e38 and 1e38. Aligned values with precisions from 24 to 53 take up four words (64 bits) of storage and can have any value between -1e307 and 1e307. Aligned values with precisions between 54 and 64 take up 6 words of storage (96 bits) and can have any value between -1e4931 and 1e4931. The default float binary precision is 23. Fixed decimal data type The fixed decimal data type can have any precision between 1 and 17, inclusive. Both unaligned and aligned values are supported. Aligned values are allocated on word (16 bit) boundaries. Unaligned values can start on any character (8 bit) boundary. Fixed decimal numbers are composed of 4-bit BCD decimal digits. The sign of a fixed decimal number is indicated by a BCD sign digit preceding the first decimal digit: a BCD digit 12 (hex C) is a "plus" sign; a BCD digit 13 (hex D) is a "minus" sign. A fixed decimal number requires precision plus one nibble (4 bits) of storage (e.g. a fixed decimal (17) would require 18 nibbles of storage or 9 bytes). The default decimal precision is 7. Float decimal data type The float decimal data type can have any precision between 1 and 17, inclusive. Both aligned and unaligned values are supported. Aligned values are allocated on word (16 bit) boundaries. Unaligned values can start on any character (8 bit) boundary. Float decimal numbers are composed of a sign and exponent header 64 03/11/91 Bull HN Product Differences Guide of 7 nibbles, followed by the mantissa consisting of 4 bit BCD decimal digits. A float decimal number requires precision plus 7 nibbles of storage rounded up to the nearest byte (e.g. a float decimal (1) requires 4 bytes, float decimal (4) requires 6 bytes, and a float decimal (17) requires 12 bytes). The default float decimal precision is 10. Pointer data type In UNIX PL/I, there are two different types of pointers: ordinary PL/I pointers and "C" pointers declared with the attribute "options (packed)". PL/I pointers are four words long (64 bits) and can be aligned or unaligned. Aligned pointers are allocated on word (16 bit) boundaries, while unaligned pointers can start on any bit boundary. PL/I pointers can contain the address of any PL/I data type. C pointers, or "options (packed)" pointers, exist so that pointer values can be traded with C routines. C pointers are two words long (32 bits) and can be aligned or unaligned. Aligned C pointers are allocated on word (16 bit) boundaries, while unaligned C pointers can start on any bit boundary. C pointers can contain only the addresses of data that are aligned on byte (8 bit) boundaries. When a PL/I pointer (including bit offset) is assigned to a C pointer, the bit offset is ignored leaving only the character or byte address. Label and entry variables Label and entry variables are four words (64 bits) long and may be aligned or unaligned. When aligned, they are allocated on word (16 bit) boundaries. When unaligned, they may be aligned on any byte (8 bit) boundary. 03/11/91 65 Product Differences Guide Bull HN Character data type Character variables may be of any length up to a logical limit of 2**31 characters. (The physical limit of the XPS address space is 2**24 characters). Both varying and nonvarying strings are supported. Character strings may be aligned or unaligned. Aligned characters strings are allocated on word (16 bit) boundaries. Unaligned character strings may start on any byte (8 bit) boundary. The default string length is 1. Bit data type Bit variables may be of any length up to a logical limit of 2**31 bits, but the physical limits of the XPS are only 2**27 bits. Varying, nonvarying, aligned and unaligned bit strings are supported. Aligned bit strings are allocated on word (16 bit) boundaries, while unaligned bit strings may start on any bit boundary. The default bit string length is 1. Complex data type The complex data type is supported as it is in Multics PL/I, with twice the declared storage being allocated for a complex variable (e.g. a "fixed bin complex (3) requires 6 bits of storage). Picture data type Picture data types are allocated as character strings, as they are in Multics PL/I. 7.3. _A_l_t_e_r_e_d _S_t_o_r_a_g_e _T_y_p_e_s The variations in the main storage types between UNIX and Multics are described below. 66 03/11/91 Bull HN Product Differences Guide EXTERNAL STATIC VARIABLES UNIX PL/I external variables are implemented in the same manner as C external variables: they are known globally within a process. These variables are not accessible to other processes, unlike on Multics where external variables are usually available for the entire login session. External variables are allocated within a task's space, and references to external variables must be resolved by the UNIX loader. External variables must be initialized once and only once by the program, or incorrect linking will result. INTERNAL STATIC VARIABLES Internal static variables are allocated within a process' address space and, as such, exist only during the life of the process; therefore, they differ from internal static variables on Multics PL/I, which survive the life of the login session. SHARED STATIC VARIABLES To simulate Multics PL/I's ability to have static variables shared between programs, UNIX PL/I provides the shared static data type. A shared static variable is declared by using the "options (shared)" clause in a PL/I declaration statement of a static variable. This causes the variable to be placed in a UNIX shared memory segment rather than in the process space. Thus, the variable retains the permanency of a Multics static variable, surviving the life of the login session. AUTOMATIC VARIABLES Automatic storage on UNIX is allocated on the stack space associated directly with each process. 03/11/91 67 Product Differences Guide Bull HN PARAMETER VARIABLES Parameter variables are implemented in UNIX PL/I as they are in Multics PL/I. For every call generated by PL/I to a PL/I procedure, an argument list structure is generated. This list can include descriptor information that describes the data type of the variables being passed as parameters. Descriptor information is generated only for "options (variable)" entrypoints and for routines accepting star length parameters. As on Multics, parameters are passed by reference. For information on parameters to C routines, see the "Extensions to PL/I" section. BASED/AREA VARIABLES The user free area for a UNIX process is included as part of the process space. There is no difference between user free areas and system free areas on the UNIX system: both are treated as references to the heap area located in the process space. Because UNIX does not support memory-mapped I/O, based variables cannot be overlayed on files on disk. 7.4. _C_o_n_d_i_t_i_o_n_s This section describes the supported conditions (including special handlers) and lists those conditions not supported. 68 03/11/91 Bull HN Product Differences Guide SPECIAL HANDLERS any_other any_other is a condition that matches any PL/I condition not dealt with by an "on unit". However, it does NOT match the special "cleanup" condition or UNIX signals which are not trapped by a specified handler. Such UNIX signals are unmatched by any_other because trapping them may interfere with UNIX operating system routines. For example, trapping the UNIX signal SIGCLD (death of a child process), would cause an error return from the UNIX "wait" routine, because "wait" itself expects the SIGCLD signal and would never get it if it was intercepted by any_other. any_other has no special meaning if it is signaled. cleanup cleanup is not an actual condition, but a means of specifying a procedure to be executed when a non-local goto unwinds the stack frame associated with the handler. It is invoked automatically as the stack is unwound, and is identical in behavior to the Multics cleanup handler. COMPILER SIGNALS The following is a list of conditions signaled by UNIX PL/I; they are essentially equivalent to the Multics signals of the same names. area overflow * bad_area_format record (f) command_abort_ return_conversion_error conversion size endfile (f) stringrange endpage (f) stringsize ** error subscriptrange fixedoverflow transmit (f) ioa_error undefinedfile (f) key (f) underflow * name (f) zerodivide * where "f" stands for a filename. ** stringsize currently does not work 03/11/91 69 Product Differences Guide Bull HN * these conditions are signaled with the names shown if they are detected by the PL/I code. If they are detected by the processor hardware, the UNIX signal SIGFPE is received. EQUIVALENT SIGNALS Multics conditions which have approximately equivalent UNIX signals: Multics signal UNIX signal Caveats _________________________________________________________________________ alrm SIGALRM illegal_modifier, SIGILL illegal_opcode out_of_bounds, SIGSEGV,SIGBUS These are not an exact match seg_fault_error since the UNIX memory model is not segmented, but they do occur in many of the same circumstances (e.g. when a program accesses an invalid location). quit SIGINT,SIGQUIT UNIX has a number of keyboard generated QUIT type signals. SIGINT is typically generated by the BREAK key and the DEL key. SIGQUIT is typically generated by the ASCII FS character. (\034) sus_ SIGHUP This is not an exact match mainly because UNIX's handling of processes differs from Multics'. Generally, the only choices for this signal are to kill the process, or to ignore it and continue. trm_ SIGKILL This cannot be trapped by a user. 70 03/11/91 Bull HN Product Differences Guide UNSUPPORTED MULTICS SUPPORT SIGNALS Multics standard conditions which are generated by or for application or system code which is not part of the supplied environment: command_query_error fortran_storage_error command_question fortran_storage_manager_error create_ips_mask_error io_error dm_not_available_ pascal_error dm_shutdown_scheduled_ timer_manager_err dm_shutdown_warning_ transaction_bj_full_ dm_user_shutdown_ transaction_deadlock_ fortran_pause transaction_lock_timeout_ These conditions could be supported if the applications associated with the conditions existed. UNSUPPORTED SYSTEM DEPENDENT SIGNALS Standard conditions which are not supported because they are system or hardware dependent: active_function_error no_execute_permission bad_dir_ no_read_permission bad_outward_call no_write_permission cput not_a_gate cross_ring_transfer not_in_call_bracket derail not_in_execute_bracket fault_tag_1 not_in_read_bracket fault_tag_3 not_in_write_bracket finish null_pointer gate_err op_not_complete illegal_procedure packed_pointer_fault illegal_return page_fault_error isot_fault parity linkage_error program_interrupt lockup record_quota_overflow lot_fault storage malformed_list_template_entry_ store mme1 system_shutdown_scheduled_ mme2 truncation mme3 undefined_pointer mme4 unwinder_error 03/11/91 71 Product Differences Guide Bull HN 7.5. _B_u_i_l_t_i_n_s The following lists all the supported and non-supported builtins for the UNIX PL/I. _B_u_i_l_t_i_n _N_a_m_e _S_u_p_p_o_r_t_e_d _M_o_d_i_f_i_e_d _C_o_m_m_e_n_t_s abs yes no acos yes no add yes no addr yes no addrel yes no after yes no allocation yes no allocn asin yes no atan yes no atand yes no baseno NO no Segment numbers have no baseptr NO no meaning on UNIX. before yes no binary yes no bin bit yes no bool yes no ceil yes no character yes no char clock yes YES Same format as on Multics. Resolution to microseconds but accuracy to 1 second. codeptr yes no collate yes no collate9 NO no A new function collate8 collate8 NEW no replaces collate9. complex yes no cplx conjg yes no convert yes no 72 03/11/91 Bull HN Product Differences Guide _B_u_i_l_t_i_n _N_a_m_e _S_u_p_p_o_r_t_e_d _M_o_d_i_f_i_e_d _C_o_m_m_e_n_t_s copy yes no cos yes no cosd yes no cosh yes no currentsize yes no date yes no decat yes no decimal yes no dec dimension yes no dim divide yes no dot yes no empty yes no environmentptr yes no erf yes no erfc yes no exp yes no fixed yes no float yes no floor yes no hbound yes no high yes no high9 NO no The new function high8 high8 NEW no replaces high9. imag yes no index yes no lbound yes no length yes no lineno yes no 03/11/91 73 Product Differences Guide Bull HN _B_u_i_l_t_i_n _N_a_m_e _S_u_p_p_o_r_t_e_d _M_o_d_i_f_i_e_d _C_o_m_m_e_n_t_s log yes no log10 yes no log2 yes no low yes no ltrim yes no max yes no maxlength yes no min yes no mod yes no multiply yes no null yes no nullo yes no offset yes no onchar yes no oncode yes no onfield yes no onfile yes no onkey yes no onloc yes no onsource yes no pageno yes no pointer yes no ptr precision yes no prec real yes no rel yes no reverse yes no round yes no rtrim yes no search yes no 74 03/11/91 Bull HN Product Differences Guide _B_u_i_l_t_i_n _N_a_m_e _S_u_p_p_o_r_t_e_d _M_o_d_i_f_i_e_d _C_o_m_m_e_n_t_s sign yes no sin yes no sind yes no sinh yes no size yes no sqrt yes no stac yes YES Bit string is of length 32. stackbaseptr yes YES The stackbaseptr on UNIX points to where the next stack frame will be allocated. stackframeptr yes no stacq yes YES Bit strings are of length 32. string yes no substr yes no sum yes no tan yes no tand yes no tanh yes no time yes no Same format as on Multics but resolution only to 1 second. (Microsecond fields are zero). translate yes no trunc yes no unspec yes no valid yes no vclock yes YES vclock will return only the time for an individual process. Resolution is in microseconds, but accuracy is to 1/60th of a second. verify yes no 03/11/91 75 Product Differences Guide Bull HN 7.6. _E_x_t_e_n_s_i_o_n_s _t_o _P_L_/_I This section describes the extensions made to Multics PL/I for the UNIX PL/I. MNEMONIC CONSTANTS UNIX PL/I allows the user to specify named constants, such as word sizes and maximum values, as compilation constants. These constants are supported as in the MR12.1 version of the Multics PL/I compiler. For example: dcl error_code_prec fixed bin options (static) init (31); dcl code fixed bin (error_code_prec); COMMUNICATION WITH C ROUTINES A new entry type has been defined in UNIX PL/I to allow for communication with UNIX C. This extension allows C routines to be called from within PL/I programs, and PL/I routines to be called from within C programs. In either case, C argument passing conventions are used; that is, the caller pushes the arguments on the stack in reverse order to their reference, and the called routine references them from the base of its stack frame. Arguments are always passed by value. Calling a PL/I Routine from a C Program A PL/I routine that is to be called from C should be declared similar to the following example: entry_1: entry (area_p, i) options (C); dcl area_p ptr options (packed); dcl i fixed bin; Only variables of certain data types may be passed to "options (C)" routines. The PL/I data types allowed, and their C counterparts, are shown below: 76 03/11/91 Bull HN Product Differences Guide _P_L_/_I _D_a_t_a _T_y_p_e _C _D_a_t_a _T_y_p_e fixed bin (1-31) int float bin (1-53) double pointer options (packed) pointer The possible return values from any such entry point are any of the allowable C parameter data types. Calling a C Routine from Within a PL/I Program A C routine may be called with any of the data types described in the preceding section. As well, PL/I character strings may be passed. Such strings must be terminated with a null byte. The allowable return values are the same as those described in the above section. Character strings CANNOT be returned from a C routine. Below is an example of such a call: %include fcntl; dcl open entry (char (*), fixed bin (31), fixed bin (31)) returns (fixed bin) options (C); dcl out_fd fixed bin; out_fd = open (("foo" || "^@"), O_CREAT + O_WRONLY + O_TRUNC, fixed ("644"b3, 31, 0)); The above call will open the file "foo" for writing, creating it if it doesn't exist, and truncating it if it does. The access mode "644" will allow the user to read and write "foo", and everyone else to read it. "out_fd" will be set to the UNIX file descriptor returned by the call. 03/11/91 77 Product Differences Guide Bull HN SHARED STATIC VARIABLES A new data type, "shared static", has been added to the UNIX PL/I compiler. For more details, see "Altered Storage Types" above. LISTING CONTROL OPTIONS Another addition to the UNIX PL/I is a series of compiler directives that can be used to tailor listings. The available directives and their uses are described below. Syntax: %options arg1, arg2, ... ; Function: Permits tailoring of the listing of source files and macro statements. A macro statement is any statement that begins with a "%". Usage: %options arg1, arg2, ... ; Arguments: identify_include Causes each include file to be identified. For example: >udd>v>o>ps>s>lex_test.i DTCM: 03/30/87 0914.5 mst Mon list Causes source statements to be listed from this point in the current and any embedded source files. (Default) listall Is the equivalent of list, list_macros, list_include, identify_include. list_include Causes include files to be listed in the source listing. list_macros Causes macro commands (starting with a % sign) to be listed in the source listing. %options macros ALWAYS will be listed. noidentify_include Stops the identification of include files in the source listing. (Default) 78 03/11/91 Bull HN Product Differences Guide nolist Stops listing of source statements, other than macro statements. nolist_macros Stops listing of macro statements, except %options macros. (Default) nolist_include Stops listing of include files at and below this inclusion level. It will not stop listing of the current source file. Defaults are: %options list, list_include, noidentify_include, nolist_macros; As an example of the %listall option, given the source file eureka.p... eureka: proc () options (main); /* This routine is a test of listing generation in the pl1 compiler. */ %options listall; /* Turn on all listing */ /* Line before include file. */ %include foo; /* Line after include file. */ dcl a fixed bin; a = 1; call uioa_ ("^d", a); end eureka; ...and the include file foo.i: /* First line of include file */ dcl uioa_ entry options (variable); /* Last line of include file */ Then the command "pl1 eureka -list" will generate the following listing: COMPILATION LISTING OF FILE eureka Compiled by: pl1 version 1.00 of March 1, 1990 Compiled at: xps2 Compiled on: Wed Mar 21 13:10:35 1990 03/11/91 79 Product Differences Guide Bull HN 1 eureka: proc; 2 3 /* This is a test of listing generation in the pl1 compiler. */ 4 5 %options listall; /* Turn on all listing */ 6 7 /* Line before include file. */ 8 %include foo; 1 1 /* First line of include file */ 1 2 dcl uioa_ entry options (variable); 1 3 /* Last line of include file */ 8 9 /* Line after include file. */ 10 11 dcl a fixed bin; 12 13 a = 1; 14 call uioa_ ("^d", a); 15 16 end eureka; SOURCE FILES USED IN THIS COMPILATION LINE NUMBER DATE MODIFIED NAME PATH 0 Wed Dec 31 17:00:00 1969 eureka.p /user1/ken/diffs/eureka.p 8 1 Thu Dec 10 09:10:40 2020 foo.i /user1/ken/diffs/foo.i [Remainder of listing not shown] 7.7. _E_f_f_i_c_i_e_n_c_y _C_o_n_s_i_d_e_r_a_t_i_o_n_s Although UNIX PL/I supports most of the features of Multics PL/I, certain features may be more (or less) efficient than their Multics equivalents. This section contains suggestions for maximizing the efficiency of ported programs. FIXED AND FLOAT DECIMAL NUMBERS Unlike Multics, UNIX does not provide direct hardware support for decimal data types. These values have to be converted to binary before an operation involving them can take place, and then the result must be converted back. Thus, these data types are expensive, and should be avoided. 80 03/11/91 Bull HN Product Differences Guide PRECISION OF FIXED BINARY NUMBERS PL/I precision rules require that operations be performed in the precision needed to store the largest possible result. For example, the addition of two "fixed bin (31)" values requires that the numbers be promoted to "fixed bin (32)"s, as the result may require that precision. On the XPS-UNIX, there is no direct hardware support for precision above 31 -- operations involving such values are emulated in software and are expensive. Thus, the minimum required precision should be used for all fixed binary variables. SHARED STATIC VARIABLES Shared static variables survive for the entire login process, but require overhead that normal static variables do not. They should be used only when normal static variables are unsuitable. PL/I POINTERS VS. C POINTERS UNIX PL/I allows two types of pointers: PL/I pointers and C pointers. PL/I pointers have both a character offset and a bit offset; C pointers (declared with the "options (packed)" attribute) have only a character offset. For normal situations, it is recommended that PL/I pointers be used; their use never results in any problems with referencing unaligned data. However, when it is known that a pointer will be used ONLY for referencing aligned or character data, C pointers should be considered as they are more efficient than PL/I pointers. BASED VARIABLES Because UNIX does not support memory-mapped I/O, based variables cannot be overlayed on files. If overlays are used to communicate information between programs, UNIX PL/I shared static variables may be suitable. For more information, see the "Multics to UNIX Migration Guide". 03/11/91 81 Product Differences Guide Bull HN 8. _U_A_S_S_I_G_N_ _D_I_F_F_E_R_E_N_C_E_S 8.1. _S_u_m_m_a_r_y The UNIX uassign_ routine is functionally equivalent to the Multics assign_ routine. All of the entrypoints in assign_ have an equivalent entrypoint in uassign_. However, the supported data types are different as the UNIX data types have different hardware representations. 8.2. _P_a_r_a_m_e_t_e_r _D_i_f_f_e_r_e_n_c_e_s uassign_, uassign_$round, and uassign_$truncate should be declared as: dcl uassign_ entry (ptr, fixed bin (15), fixed bin (31), ptr, fixed bin (15), fixed bin (31)); The fixed bin (31) arguments are the encoded_precision. The declaration of encoded precision can be found in the encode_prec.i include file, and is defined as follows: dcl 1 encoded_precision based aligned, 2 scale fixed bin (15) unaligned, 2 prec fixed bin (16) unsigned unaligned; uassign_$computational should be declared as follows: dcl uassign_$computational entry (ptr, ptr, fixed bin (31)); The pointers in uassign_$computational point to structures that are defined in the include file comp_data.i; the structures define the attributes of the arguments to be converted. 82 03/11/91 Bull HN Product Differences Guide 8.3. _U_N_I_X _D_a_t_a _T_y_p_e_s The data types supported by uassign_ are as follows: Real_fixed_bin_sgl_dtype, Complex_fixed_bin_sgl_dtype, Real_fixed_bin_dbl_dtype, Complex_fixed_bin_dbl_dtype, Real_fixed_bin_quad_dtype, Complex_fixed_bin_quad_dtype, Real_fixed_bin_sgl_uns_dtype, Real_fixed_bin_dbl_uns_dtype, Real_fixed_bin_quad_uns_dtype, Real_float_bin_sgl_dtype, Complex_float_bin_sgl_dtype, Real_float_bin_dbl_dtype, Complex_float_bin_dbl_dtype, Real_float_bin_ext_dtype, Complex_float_bin_ext_dtype, Real_fixed_dec_4ls_dtype, Complex_fixed_dec_4ls_dtype, Real_fixed_dec_8ls_dtype, Complex_fixed_dec_8ls_dtype, Real_float_dec_4_dtype, Complex_float_dec_4_dtype, Real_float_dec_8_dtype, Complex_float_dec_8_dtype, Char_dtype, Char_varying_dtype, Bit_dtype, Bit_varying_dtype These data types are defined in the include file desc_types.i. Note that the decimal types Real_fixed_dec_8ls_dtype, Complex_fixed_dec_8ls_dtype, Real_float_dec_8_dtype, and Complex_float_dec_8_dtype are not directly supported by the PL/I compiler; they exist only for support of the picture data type. 03/11/91 83 Product Differences Guide Bull HN 9. _U_I_O_X_ _D_I_F_F_E_R_E_N_C_E_S Function UNIX uiox_ allows applications which use iox_ for their I/O on the Multics system to be ported, with minimal changes, to a UNIX system. UNIX application programs will use the uiox_ I/O system by calling entrypoints in the "uiox_" module. The function of each routine remains the same as on Multics, except as noted in the "Quick Reference" section of this guide. 9.1. _N_a_m_e _C_h_a_n_g_e_s The Multics name iox_ has been changed to uiox_ on UNIX. This name change is required because changes to the parameters have been made in order to adapt to the UNIX architecture. (Standard practice dictates that a change in calling parameters requires a change in a procedure's name.) 9.2. _P_a_r_a_m_e_t_e_r _C_h_a_n_g_e_s There are five parameter changes to make note of: 1) the Multics IOCB pointer (72 bits) is replaced by the ATEL (Attach Table Entry Locator, bit(32)) on UNIX; 2) the Multics fixed bin(35) error table codes are changed to fixed bin(31) on UNIX; 3) all instances of fixed bin(17) are changed to fixed bin(15) on UNIX; 4) all fixed bin(21) are changed to fixed bin(31); and 5) all char(256) will be changed to char (*). 9.3. _U_n_s_u_p_p_o_r_t_e_d _O_p_e_r_a_t_i_o_n_s The operation iox_$propagate is not supplied, as it is an optimization routine for the syn_ I/O module which is not supported. The undocumented operations attach_ioname and attach_iocb are not provided under uiox_. 84 03/11/91 Bull HN Product Differences Guide iox_$find_iocb_n is not implemented since the information returned by the routine can be easily rendered obsolete in the UNIX multiprocess environment. 9.4. _N_e_w _O_p_e_r_a_t_i_o_n_s Two new operations replace the Multics iox_$find_iocb_n operation; they provide the user with better control of the I/O switches. These two new operations are uiox_$list_switches User programs can retrieve information from the Attach Table by using the list_switches operation (for determining which switches are active). uiox_$switch_data User programs can extract data from the Attach Table for a particular switch using the switch_data operation. For a detailed explanation of these two new operations, refer to uiox_ in the Quick Reference section of this guide. 9.5. _R_e_n_a_m_e_d _O_p_e_r_a_t_i_o_n_s The following four operations are renamed since uiox_ does not implement switches via IOCBs. _M_u_l_t_i_c_s _N_a_m_e _U_N_I_X _N_a_m_e iox_$destroy_iocb uiox_$destroy_switch iox_$detach_iocb uiox_$detach_switch iox_$find_iocb uiox_$find_switch iox_$look_iocb uiox_$look_switch 9.6. _C_o_n_c_u_r_r_e_n_t _v_s _S_e_q_u_e_n_t_i_a_l _M_u_l_t_i_p_r_o_c_e_s_s_i_n_g The Multics system does not allow multiprocessing of I/O operations. Each I/O switch belongs to one, and only one, process. However, due to the nature of the UNIX process environment, this must be allowed for under UNIX. 03/11/91 85 Product Differences Guide Bull HN The access multiple processes have to the I/O switches can be of either a concurrent or a sequential nature. Concurrent multiprocessing access means that any process in the login process group may request an I/O operation on the switch at any time, even if other processes are active and using the switch. Sequential multiprocessing requires that only one process use the switch at any given time. Additionally, once a process stops using a switch and another starts, the first may not resume processing using that switch. Since Multics does not have multiprocessing, all existing Multics code to be ported to UNIX will use sequential multiprocessing. Concurrent multiprocessing may arise from native UNIX applications developed or modified to use uiox_, or from Multics applications modified to use the UNIX multiprocessing features. uiox_ allows for concurrent multiprocessing. Any process may perform any I/O operation without regard for what the other processes are doing, so long as no process closes or detaches the switch. 9.7. _A_t_t_a_c_h _T_a_b_l_e The Attach Table is a combination of the Multics IOCB and the hash table of switch names which makes up the "Logical Attach Table" on Multics. Under UNIX, it is an array of entries in shared static storage. This is a shared memory segment maintained by the PL/I runtime, and made accessible to all processes in the login process group. On Multics, when an iox_ routine is invoked, one of its parameters is a pointer which locates the switch being referenced in the Attach Table. The pointer points to the I/O Control Block. This IOCB pointer is used to indicate the switch to be used for the iox_ operation. The UNIX uiox_ implementation replaces the IOCB pointer with a software construct called an Attach Table Entry Locator (ATEL). The ATEL is given to the user in the form of a PL/I bit(32) datum. 9.8. _S_t_a_t_i_c _S_w_i_t_c_h _I_n_i_t_i_a_l_i_z_a_t_i_o_n The static ATELs uiox_$user_io, uiox_$user_input, uiox_$user_output, and uiox_$error_output are referenced as "external static bit(32)", and are declared in the uiox_dcls.i include file. 86 03/11/91 Bull HN Product Differences Guide 9.9. _O_p_e_r_a_t_i_o_n _U_n_d_e_r _U_N_I_X When a program wishes to perform I/O, it makes calls to the uiox_ module. The uiox_ module is linked with the program, and acts as an interface to the I/O module and maintains the Attach Table. The application program begins the I/O by making a call to either uiox_$find_switch, uiox_$attach_name, or uiox_$attach_switch. After attaching the switch, the user program must open it. If the switch was acquired via the find_switch entry, it may have already been opened. If it has already been opened, the open operation either will be omitted or attempted; if attempted, an error code reporting that the switch is already open will be returned. Once a switch is opened, I/O operations may or may not be performed, depending on the mode of opening. In addition, depending on which I/O module is being used, the routines uiox_$control and uiox_$modes also may or may not be called after attaching the switch, but before opening it. When the user program is finished doing I/O on a switch using the current opening mode, the switch is closed by calling uiox_$close. If the program wishes to do I/O using a different opening mode, the switch may be reopened at this time and further I/O operations may be performed (based on the new open mode). When the process is finished with the switch, uiox_$detach_switch is called. At this point the switch is available for reuse, but only under the same name as before. This mimics the behavior of a detached, but undestroyed, Multics IOCB. In order to dissociate the name from the switch and free the table entry, the user must call the uiox_$destroy_switch entry. 9.10. _L_o_c_a_t_i_n_g _A_n _I_/_O _M_o_d_u_l_e uiox_ locates I/O modules through the use of the environment variable PATH. In order for uiox_ to find the I/O modules, the PATH variable must include the path "/usr/lbin". Failure to find the I/O module will result in an error code being returned. On Multics, I/O modules are located by using the Multics search rules. 03/11/91 87 Product Differences Guide Bull HN 10. _V_F_I_L_E_ _D_I_F_F_E_R_E_N_C_E_S Function: vfile_ is an I/O module supporting I/O to/from files in the UNIX storage system. The vfile_ I/O module is not invoked directly, but via the uiox_ I/O system. 10.1. _U_n_s_u_p_p_o_r_t_e_d _v_f_i_l_e_ _A_r_g_u_m_e_n_t_s The following Multics vfile_ control arguments are not supported by UNIX vfile_: -ssf used to prevent a Multics vfile_ from exceeding 255 pages in length, and becoming a Multi-Segment File (MSF). The XPS-100 UNIX implementation does not have MSFs. -transaction used with the Multics transaction_call command for implementing a primitive form of the Data Management facility. This facility is no longer in use. -checkpoint used with the control orders "checkpoint" and "rollback". These control orders are no longer documented on Multics. -blocked used with the blocked file type. Blocked files are not being implemented under UNIX. 10.2. _S_u_p_p_o_r_t_e_d _F_i_l_e _T_y_p_e_s UNIX vfile_ supports three of the four Multics vfile_ file types: unstructured, sequential, and indexed files. The blocked file type is not supported. 10.3. _U_n_s_u_p_p_o_r_t_e_d _C_o_n_t_r_o_l _O_r_d_e_r_s The following Multics control orders are not supported by UNIX vfile_. 88 03/11/91 Bull HN Product Differences Guide checkpoint used with transaction processing, which is no longer supported on Multics. exclude largely unused on Multics. MRDS and LINUS, which use this order, are not part of the Migration Package. max_reclen used only by blocked files, which are not being supported on UNIX. record_status may return pointers into the file. The XPS-100 version of UNIX does not support memory mapped files, therefore, this function cannot be provided. This order performs other functions as well, which are being provided by new control orders (described below). select closely related to exclude, and is not supported for the same reasons. rollback used with transaction processing, which is no longer supported on Multics. 10.4. _N_e_w _C_o_n_t_r_o_l _O_r_d_e_r_s The following new control orders provide functions similar to the Multics record_status control order. create_rec creates a record, optionally bypassing the file index or locking the record. inc_ref_count increments the user reference count for a specific record. set_record_lock locks or unlocks a specific record. Details on locking may be found in the section "Record locking". 03/11/91 89 Product Differences Guide Bull HN 10.5. _M_u_l_t_i_p_l_e _O_p_e_n_i_n_g_s Various classes of multiple openings are known to vfile_, and the interactions between them are defined. The four classes of multiple openings are 1) Openings for input without "-share" 2) Openings for output or inputoutput without "-extend" 3) Openings for update without "-share", and for output or inputoutput without "-share" but with "-extend" 4) Openings with "-share". No concurrent opening protection is available for unstructured files. The following paragraphs apply only to indexed and sequential files. Any number of concurrent class 1 openings is allowed. This class of opening never modifies the file. It is not detected by other classes of openings, and it is possible that the presence of other such openings may disrupt existing class 1 openings. Any class 2 or class 3 (and some class 4) openings in existence when a class 1 opening occurs will be detected and cause the class 1 opening to fail. This mimics Multics operation. Only one class 2 opening is allowed for a file. Multics does not detect the existence of other opening classes when this class of open is attempted. The UNIX implementation is capable of detecting other class 2 and 3 openings, as well as some class 4 openings, since the file lock is stored outside the file proper. The existence of such openings will cause the class 2 open attempt to fail. Only one class 3 opening is allowed for a file. Multics detects multiple openings of this class (and some of class 4). The UNIX implementation will also detect existing class 2 openings. If a class 4 opening exists, but is not detected, then the class 3 opening will be allowed, and will prevent the class 4 opening from locking the file until the class 3 opening closes the file. An exception to this rule occurs if the class 3 opening is an indexed file attached without the -exclusive control argument. In this case existing class 4 openings share read access to the file with the class 3 opening, but write access and additional class 4 openings are rejected. Any number of class 4 openings are allowed for a file. Such openings may conflict with previous openings of other classes, as described in the preceeding paragraphs. Class 4 openings co-ordinate themselves using the file lock, or record locks. The file lock is set by vfile_ during update operations, and may explicitly be set by an application using the set_file_lock control order. 90 03/11/91 Bull HN Product Differences Guide 10.6. _R_e_c_o_r_d _L_o_c_k_i_n_g The UNIX "fcntl" locking protocol provides for advisory locking of regions of a file by a UNIX process. The UNIX kernel does not recognize the sharing of these locks among the processes of a process group, or the exclusion of multiple openings within a single process. This has implications for the handling of vfile_ record locks. First, the record lock must be set and released by the same process. Also, this process must remain active during processing (under the record lock) by other processes in the process group. Premature termination of the lock-holding process will release the record lock. Finally, the UNIX kernel associates locks with files, not openings. This causes all openings of a given file (referenced by the process holding a record lock in one opening) to act as if it has the record lock. These deviations from the Multics standard are major, but only crop up in exceptional circumstances. Normally, a vfile_ application is implemented as a single program, and would run as a single UNIX process. Likewise, it is unusual to see multiple openings of a single file used by a single application. 10.7. _R_e_c_o_r_d _D_e_s_c_r_i_p_t_o_r_s _a_n_d _U_s_e_r _R_e_f_e_r_e_n_c_e _C_o_u_n_t Multics vfile_ allows specification of records via a unique identifier (called a descriptor) which is a 36-bit quantity composed of two 18-bit binary values: the MSF component number, and the word offset of the record within the component. Under UNIX, the descriptor is implemented as a 32-bit binary value containing the offset of the record (in bytes) from the beginning of the file. This works fine until record relocation occurs while a descriptor is held by an application. Multics avoids this by allowing the application to increment or decrement the reference count of the record via the "record_status" control order. Under UNIX this functionality is replaced with the "inc_ref_count" control order. When a record descriptor which refers to a logically deleted record is given to vfile_, the error table entry "error_table$no_record" is returned. If a descriptor is given which refers to a relocated record, then the operation is performed as if the descriptor referred to the relocated record. Once the relocation records have been removed, references through the record descriptor produce undefined results. 03/11/91 91 Product Differences Guide Bull HN An additional change from the Multics implementation is that the UNIX version will keep two separate reference counts -- one used internally for tracking index updates, and the "user reference count" which is manipulated only by the "inc_ref_count" control order. 10.8. _C_o_n_t_r_o_l _O_r_d_e_r_s Many of the vfile_ control orders use structures to hold information. All the control order structures have been changed to reflect the 32-bit architecture of the XPS-100. Only those control orders which have additional changes are listed in this section. For a detailed look at these structures, refer to the vfile_ info file. CREATE RECORD This is a new control order to replace a portion of the functionality lost by the removal of the Multics record_status control order. Its purpose is to create a record, and optionally set various attributes of the record, all in a single file operation. It may be used only on indexed files open for keyed sequential output, keyed sequential update, direct output, or direct update. ERROR STATUS The error_status control order is identical to the Multics implementation, except for changes to 32-bit on UNIX. The fields of this structure have the same meaning and use as their Multics counterparts, except that the version field must now be set to error_info_version_2. FILE STATUS The file_status control order is implemented virtually identical to the Multics implementation, except for the action field in the indx_info structure which is set to zero and does not contain any useful information. Most of the changes reflect only the change to a 32-bit hardware platform. 92 03/11/91 Bull HN Product Differences Guide The content and meaning of the fields of these structures are the same as on Multics, except for "version" (Multics) (which becomes "file_version" under UNIX) and "program_version" (Multics) (which becomes "vfile_version" under UNIX). Since the blocked file type is not supported under UNIX vfile_, the Multics "blk_info" structure is not provided. The info_version fields of the structures have been changed from fixed binary data to character string data. GET KEY The get_key control order is the same as the Multics version, except for changes required for the 32-bit hardware platform. The contents and usage of this structure are identical to the Multics version of this control order, except that the version required is now gk_info_version_1. INCREMENT REFERENCE COUNT The inc_ref_count control order is a new order to the UNIX version of vfile_. Its function is to increment or decrement the user reference count of a specified record. On Multics this function is provided by the record_status control order. Since record_status is not present under UNIX, this new method of dealing with reference counts is required. The inc_ref_count control order may be used only on indexed files opened for keyed sequential output, keyed sequential update, direct output, or direct update. The use of stationary record reference counts is somewhat different under UNIX than it was on Multics. The UNIX implementation provides separate counts for internal references (via the file index), and external (user) references. This order can affect only the user reference count. SET RECORD LOCK The set_record_lock control order is a new control order that is used to set record locks. On Multics, this function is performed by the record_status control order (which has not been implemented under UNIX). 03/11/91 93 Product Differences Guide Bull HN set_record_lock may be used with indexed files opened for keyed sequential output, keyed sequential update, direct output, or direct update, and with the -share control argument specified in the attach description. If the lock cannot be changed within the current wait time, then a non-zero error code is returned. If any opening has a record lock set in a file, then no other opening may acquire the file lock. This interaction does not occur on Multics. SET WAIT TIME The set_wait_time order is similar to the Multics implementation, except that only the one version of the input structure is used. This modified input structure performs all the functions of both Multics versions. The new structure contains the fields new_wait_time, and collect_delay. These fields, when in use, have the same meaning as on Multics. If the value of a field is negative, it is not in use and the parameter affected by that field will not be changed by the call. 94 03/11/91 ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved