1 08/22/83  initiate_file_
  2 
  3 The initiate_file_ subroutine contains entry points for making a
  4 segment or archive component known with a null reference name.
  5 
  6 
  7 Entry points in initiate_file_:
  8    (List is generated by the help command)
  9 
 10 
 11 :Entry:  initiate_file_:  03/29/82 initiate_file_
 12 
 13 
 14 Function:  The initiate_file_ entry point, given a directory name,
 15 entry name, and access mode, checks that the user's process has at
 16 least the desired access on the specified segment.  If so, the segment
 17 is initiated with a null reference name.  This entry point returns a
 18 pointer to the base of the segment and the bit count of the segment.
 19 
 20 
 21 Syntax:
 22 declare initiate_file_ entry (char (*), char (*), bit (*), pointer,
 23      fixed binary (24), fixed binary (35));
 24 call initiate_file_ (dirname, entryname, mode, seg_ptr, bit_count,
 25      code);
 26 
 27 
 28 Arguments:
 29 dirname
 30    is the pathname of the containing directory.  (Input)
 31 entryname
 32    is the entryname of the segment.  (Input)
 33 mode
 34    is the required access mode to the segment.  (Input) The first three
 35    bits correspond to the modes read, execute, and write.  The
 36    remaining bits, if any, must be zero.  Named constants for the
 37    access modes are declared in access_mode_values.incl.pl1.
 38 seg_ptr
 39    if the segment was made known, this is a pointer to the base of the
 40    segment.  Otherwise, this is null.  (Output)
 41 
 42 
 43 bit_count
 44    is the bit count of the segment.  (Output)
 45 code
 46    is a standard status code.  (Output)  It may have one of the
 47    following values:
 48    error_table_$no_r_permission
 49         read permission was required but not present
 50    error_table_$no_e_permission
 51         execute permission was required but not present
 52    error_table_$no_w_permission
 53         write permission was required but not present
 54 
 55 
 56 Notes:  The specified segment must exist, and the user must have
 57 nonnull access to it, as well as the required modes, in order to make
 58 it known.
 59 
 60 If making the segment known encounters the error_table_$segknown status
 61 code, a zero status code is returned instead.  This enables the user of
 62 this entry point to test either the returned pointer, or the status
 63 code, to indicate whether the segment was made known or not.
 64 
 65 The hcs_$terminate_noname entry point or the terminate_file_ subroutine
 66 should be used to make the segment unknown.
 67 
 68 
 69 :Entry:  create:  09/22/86  initiate_file_$create
 70 
 71 
 72 Function:  initiates the specified segment with a null reference
 73 provided that the user's process has at least the desired access to the
 74 segment.  If the segment does not exist, it will be created .
 75 
 76 
 77 Syntax:
 78 dcl  initiate_file_$create entry (char (*), char (*), bit (*), pointer,
 79           bit (1) aligned, fixed binary (24), fixed binary (35));
 80 call initiate_file_$create (dirname, entryname, mode, seg_ptr, created,
 81           bit_count, code);
 82 
 83 
 84 Arguments:
 85 dirname
 86    is the pathname of the containing directory.  (Input)
 87 entryname
 88    is the entryname of the segment.  (Input)
 89 mode
 90    is the required access mode to the segment.  The first three bits
 91    correspond to the modes read, execute, and write.  The remaining
 92    bits, if any, must be zero.  Named constants for the access modes
 93    are declared in access_mode_values.incl.pl1.  (Input)
 94 seg_ptr
 95    is set to a pointer to the base of the segment if successfull;
 96    otherwise, it is set to null.  (Output)
 97 created
 98    is set to "1"b if the segment did not exist and was created by this
 99    call; otherwise, it is set to "0"b.  (Output)
100 
101 
102 bit_count
103    is set to the bit count of the segment.  (Output)
104 code
105    is a standard status code.  (Output)  It may have one of the
106    following values:
107    error_table_$no_m_permission
108         the segment did not exist and could not be created with the
109         required access.
110    error_table_$no_r_permission
111         read permission was required but not present
112    error_table_$no_e_permission
113         execute permission was required but not present
114    error_table_$no_w_permission
115         write permission was required but not present
116 
117 
118 Notes:
119 If making the segment known encounters the error_table_$segknown status
120 code, a zero status code is returned instead.  This enables the user of
121 this entry point to test either the returned pointer, or the status
122 code, to indicate whether the segment was made known or not.
123 
124 The terminate_file_ subroutine should be used to make the segment
125 unknown.  If the segment was create by this call and the caller
126 terminates abnormally or its cleanup handler is invoked, the caller may
127 use the delete option of terminate_file_ to remove the segment that was
128 created.
129 
130 
131 :Entry:  component:  03/09/82  initiate_file_$component
132 
133 
134 Function:  This entry point can make either a segment or an archive
135 component known with a null reference name.
136 
137 If the component name is null, this entry point is identical to
138 initiate_file_.
139 
140 Otherwise, the directory name and entry name arguments are assumed to
141 specify an achive, and the component name specifies a component within
142 that archive.  If the user's process has at least the desired acces on
143 the archive segment, and the user desires no more than read access,
144 then the archive is made known with a null reference name, and a
145 segment number is assigned.  This entry point returns a pointer to the
146 base of the component and the bit count of the component.
147 
148 
149 Syntax:
150 declare initiate_file_$component entry (char (*), char (*), char (*),
151      bit (*), pointer, fixed binary (24), fixed binary (35));
152 call initiate_file_$component (dirname, entryname, component_name,
153      mode, component_ptr, bit_count, code);
154 
155 
156 Arguments:
157 dirname
158    is the pathname of the containing directory.  (Input)
159 entryname
160    if component_name is null, this is the entryname of the segment.
161    Otherwise, this is the entryname of an archive.  The archive suffix
162    must be supplied.  (Input)
163 component_name
164    is null, or is the name of a component in the archive.  (Input)
165 mode
166    is the required access mode to the segment.  (Input) The first three
167    bits correspond to the modes read, execute, and write.  The
168    remaining bits, if any, must be zero.  Named constants for the
169    access modes are declared in access_mode_values.incl.pl1.
170 
171 
172 component_ptr
173    if the segment was made known, this is a pointer to the base of the
174    segment or the base of the archive component.  Otherwise, this is
175    null.  (Output)
176 bit_count
177    is the bit count of the segment or archive component.  (Output)
178 code
179    is a standard status code.  (Output)  In addition to the above
180    values, it may have:
181    error_table_$archive_component_modification
182         write permission was required on an archive component
183 
184 
185 Notes:  The notes for the initiate_file_ entry point apply to this
186 entry point also.
187 
188 If a nonnull component name is specified, the following constraints
189 apply to the use of this entry point:
190  (1) The component may not be modified.  Only read access is permitted.
191  (2) The component is guaranteed to be contiguous and aligned on a word
192      boundary.  It is not guaranteed to have any other alignment.
193  (3) No explicit dependence on the format of archives is permitted.
194      This means that only the data starting at the pointer and
195      extending as far as the bit count may be referenced.  No data
196      before or after the component may be referenced.