1 12/01/86 dsl_
2
3 This subroutine supplies entry points for the functions required in
4 opening, manipulating, and closing a data base.
5
6
7 Examples of its use are documented in the MRDS Reference Manual AW53.
8
9
10 Entry points in dsl_:
11 List is generated by the help command
12
13
14 :Entry: close: 06/17/86 dsl_$close
15
16 Function: This entry causes the specified data bases to be closed and
17 made unavailable for processing.
18
19
20 Syntax:
21 declare dsl_$close entry options variable;
22 call dsl_$close data_base_index1 ... data_base_indexn code;
23
24
25 Arguments:
26 data_base_indexi Input fixed bin35
27 is the integer returned by dsl_$open that designates the currently
28 open data bases that are to be closed.
29 code Output fixed bin35
30 is a standard status code.
31
32
33 :Entry: close_all: 06/17/86 dsl_$close_all
34
35 Function: This entry closes all data bases that are currently open in
36 the user's process.
37
38
39 Syntax:
40 declare dsl_$close_all entry options variable;
41 call dsl_$close_all code;
42
43
44 Arguments:
45 code output fixed bin35
46 is the standard status code and is 0 if all data bases are
47 successfully closed or if no data bases are open.
48
49
50 :Entry: compile: 12/01/86 dsl_$compile
51
52 Function: This entry compiles or pre-translates a selection
53 expression for later use in the current process, for retrieval, modify,
54 delete, and define_temp_rel operations. A previously compiled
55 selection expression can be deleted or redefined through this
56 entrypoint. A selection expression can be compiled at any time in the
57 life of an open data base and saved for future use in that opening.
58
59
60 Syntax:
61 declare dsl_$compile entry options variable;
62 call dsl_$compile data_base_index selection_expression se_index
63 se_value1 ... se_valuen code;
64
65
66 Arguments:
67 data_base_index Input fixed bin35
68 is the index returned by dsl_$open to designate the data base.
69 selection_expression Input char *
70 is a character string as defined at the beginning of this section.
71 It may contain .V. argument substitution characters in all normal
72 places. These are filled in at the time the selection expression is
73 compiled. Argument substitution characters of the form .X. may be
74 used in all places in the where clause where .V. is appropriate
75 except functions and expressions to specify that this value is to
76 be filled in at the time that the selection expression is used.
77
78
79 se_index Input/Output fixed bin35
80 is an integer used to identify a compiled selection expression. If
81 the se_index is 0 on input a new compiled selection expression is
82 defined and the index for the newly compiled selection expression is
83 returned. If the se_index is greater than zero on input and a
84 compiled selection expression with that index is found it is
85 redefined to the new selection expression. If the se_index is less
86 than zero on input and a compiled selection expression with that
87 index is found it is deleted and the selection expression is
88 ignored.
89 se_value_i Input
90 is a selection expression value for each control code designated by
91 .V. appearing in the selection expression. These must be
92 specified so as to correspond in order and quantity with the control
93 codes specified in the selection expression.
94
95
96 code Output fixed bin35
97 is a standard MRDS status code. A value of 0 indicates that no
98 error occurred.
99
100
101 Notes: Any .V. argument substitution characters supplied in the
102 selection expression must have matching arguments supplied in the call
103 to dsl_$compile. They are then considered to be constant and cannot be
104 changed later. Any .X. argument substitution characters supplied in
105 the selection expression must have matching arguments supplied in the
106 call that references the compiled selection expression not the call to
107 dsl_$compile. The arguments supplied to satisfy a .X. must have the
108 same data type as that of the data base attribute it is being compared
109 to.
110
111
112 :Entry: declare: 06/17/86 dsl_$declare
113
114 Function: This entry makes a user-defined function known to MRDS while
115 processing the specified data base. After it is declared a
116 user-defined function may be used exactly as a MRDS built-in function.
117 If a user-defined function has the same name as a built-in function
118 the user-defined function is referenced.
119
120
121 Syntax:
122 declare dsl_$declare entry fixed bin35 char* fixed bin35;
123 call dsl_$declare db_index fn_name code;
124
125
126 Arguments:
127 db_index Input
128 is the index returned by dsl_$open that designates the data base.
129 fn_name Input
130 is the name of the function being declared.
131 code Output
132 is a standard status code.
133
134
135 Notes: Built-in functions are provided as a standard part of MRDS and
136 need not be declared.
137
138
139 User-defined functions may be written in PL/I COBOL or FORTRAN. MRDS
140 generates a call that is equivalent to:
141
142 return_val = fn_name$fn_name arg1 ... argn
143
144
145 Restrictions on arguments to user-defined functions are 1 No star *
146 extents are permitted in the declarations for return_val or argi; 2
147 Data types are restricted to those data types permitted in a MRDS data
148 base i.e. pointers entries labels structures offsets and arrays
149 are not allowed.
150
151
152 :Entry: define_temp_rel: 06/17/86 dsl_$define_temp_rel
153
154 Function: This entry allows the user to explicitly create delete or
155 redefine a temporary relation that can be used by the current process
156 for retrieval operations in the same manner as any predefined permanent
157 data base relations.
158
159
160 The only operations that can be performed on a temporary relation are
161 the "define_temp_rel" "retrieve" and "get_population". After a
162 temporary relation is defined it is referenced by specifying a ".V."
163 argument in the range clause and supplying the appropriate rel_index in
164 the dsl_ call argument list. A temporary relation cannot be used in
165 the -select clause except for the dsl_$retrieve call.
166
167
168 Syntax:
169 declare dsl_$define_temp_rel entry options variable;
170 call dsl_$define_temp_rel data_base_index selection_expression
171 se_index se_value1 .. se_index se_valuen rel_index code;
172
173
174 Arguments:
175 data_base_index Input fixed bin35
176 is the index returned by dsl_$open that designates the data base.
177 selection_expression Input char*
178 is a character string as defined at the beginning of this section
179 with at least one * in the -select clause to define the temporary
180 relation key. The attribute names given in the select clause must
181 be unique. This character string may be a constant or a variable
182 declared either character varying or non-varying.
183 se_index Input fixed bin35
184 is an integer used to refer to a compiled selection expression. It
185 is required only if the selection expression is "-compiled".
186
187
188 se_valuei Input
189 is a selection expression value for each argument substitution
190 designated by .V. or .X. appearing in the
191 <selection_expression> including temporary relation rel_index
192 designations. These must be specified so as to correspond in order
193 and quantity with the argument substitution specified in the
194 <selection_expression. If the selection expression is "-compiled"
195 then the selection expression value is substituted for the .X.
196 value in the where clause that has to be satisfied. These values
197 are supplied in the order in which they occur in the selection
198 expression used in the call to dsl_$compile. If the specified data
199 type does not equal the attribute data type the value
200 mrds_error_$inv_data_type is returned in the code.
201
202
203 rel_index Input/Output fixed binary35
204 is an integer. If rel_index is 0 on input a new temporary relation
205 is defined and the index for the newly created temporary relation is
206 returned in rel_index. If rel_index is greater than 0 on input and
207 if a temporary relation possessing this index is already in
208 existence that temporary relation is redefined. If rel_index is
209 less than zero and a temporary relation with that rel_index exists
210 then that temporary relation is deleted and the selection expression
211 is ignored.
212 code Output fixed bin36
213 is a standard status code. A value of 0 indicates that no error
214 occurred.
215
216
217 Notes: If a duplicate of the temporary relation key is found while
218 creating the temporary relation it is ignored i.e. not stored
219 without warning.
220
221
222 If no data satisfied the selection expression then an unpopulated
223 temporary relation is created. The population can be determined by a
224 call to dsl_$get_population.
225
226
227 For shared openings relations specified in the range clause must have
228 read_attr scope set.
229
230
231 For attribute level security attributes specified in the select and
232 where clauses must have read_attr access.
233
234
235 :Entry: delete: 06/17/86 dsl_$delete
236
237 Function: This entry allows the user to delete one or more tuples from
238 the same relation of an opened data base. The user must have
239 read-write permission to the relation. All attributes in the relation
240 must be specified as being selected and if the data base is being
241 referenced by means of a data submodel all attributes of the relation
242 must be defined in the submodel. All selected tuples are deleted.
243
244
245 Syntax:
246 declare dsl_$delete entry options variable;
247 call dsl_$delete data_base_index selection_expression se_index
248 se_value1 ... se_valuen code;
249
250
251 Arguments:
252 data_base_index Input fixed bin35
253 is the index returned by dsl_$open that designates the data base.
254 selection_expression Input char*
255 is a character string as defined at the beginning of this section.
256 However the select clause must specify all attributes in the
257 relation. This character string may be a constant or a variable
258 declared character varying or non-varying.
259 se_index Input fixed bin35
260 is an integer used to refer to a compiled selection expression. It
261 is required only if the selection expression is "-compiled".
262
263
264 se_valuei Input
265 is a selection expression value for each argument substitution
266 designated by .V. or .X. appearing in the
267 <selection_expression> including temporary relation rel_index
268 designations. These must be specified so as to correspond in order
269 and quantity with the argument substitution specified in the
270 <selection_expression. If the selection expression is "-compiled",
271 then the selection expression value is substituted for the .X.
272 value in the where clause that has to be satisfied. These values
273 are supplied in the order in which they occur in the selection
274 expression used in the call to dsl_$compile. If the specified data
275 type does not equal the attribute data type, the value
276 mrds_error_$inv_data_type is returned in the code.
277
278
279 code Output fixed bin35
280 is a standard status code. A value of 0 indicates that no error
281 occurred. A value corresponding to mrds_error_$tuple_not_found
282 indicates that no error occurred and that no data satisfied the
283 selection expression.
284
285
286 Notes: For shared openings, the relation must have delete_tuple permit
287 scope set.
288
289
290 For attribute level security, the relation must have delete_tuple
291 access and any attributes specified in the where clause must have
292 read_attr access.
293
294
295 :Entry: dl_scope: 06/17/86 dsl_$dl_scope
296
297 Function: This entry deletes all or part of a previously specified
298 scope from the user's current scope.
299
300
301 Syntax:
302 declare dsl_$dl_scope entry options variable;
303 call dsl_$dl_scope db_index rel_name1 permit_ops1 prevent_ops1
304 ... rel_namen permit_opsn prevent_opsn code;
305
306
307 Arguments:
308 db_index Input fixed bin35
309 is the index returned by dsl_$open that designates the data base.
310 rel_namei Input char*
311 is the name of the relations to be included in the scope.
312 permit_opsi Inputfixed bin
313 the sum of the codes for the operations no longer granted to the
314 user's process on the specified relation as defined in set_scope.
315 See "Note" below for a description of appropriate codes.
316 prevent_opsi Input fixed bin
317 the sum of the codes for the operations no longer denied to other
318 processes on the specified relation as defined in set_scope. See
319 "Note" below for a description of appropriate codes.
320 code Output fixed bin35
321 is a standard status code.
322
323
324 Notes: Scope codes for operations to be prevented or permitted are as
325 follows:
326
327
328 Scope
329 Code Operation
330
331 0 null
332 1 read_attr or read
333 2 append_tuple or store
334 4 delete_tuple or delete
335 8 modify_attr or modify
336
337
338 Current scope settings can be determined by a call to dsl_$get_scope.
339
340
341 :Entry: dl_scope_all: 06/17/86 dsl_$dl_scope_all
342
343 Function: This entry deletes all remaining scope tuples from the
344 user's current scope.
345
346
347 Syntax:
348 declare dsl_$dl_scope_all entry fixed bin35 fixed bin35;
349 call dsl_$dl_scope_all db_index code;
350
351
352 Arguments:
353 db_index Input
354 is the index returned by dsl_$open that designates the data base.
355 code Output
356 is a standard status code. It is 0 if no scope is set prior to the
357 call to dsl_$dl_scope_all.
358
359
360 :Entry: get_attribute_list: 06/17/86 dsl_$get_attribute_list
361
362 Function: This entry returns information on the attributes in the view
363 of the given relation provided by the user's opening.
364
365
366 Syntax:
367 declare dsl_$get_attribute_list entry fixed bin35
368 char* ptr fixed bin ptr fixed bin35;
369 call dsl_$get_attribute_list db_index relation_name
370 area_ptr structure_version mrds_attribute_list_ptr
371 error_code;
372
373
374 Arguments:
375 db_index Input fixed bin35
376 is the integer returned by dsl_$open for the opening the user wishes
377 to reference.
378 relation_name Input char*
379 is the name of the relation in the user's view for which the
380 attribute information is desired.
381 area_ptr Input pointer
382 is a pointer to a user-supplied freeing area, in which the attribute
383 information is to be allocated.
384 structure_version Input fixed bin
385 is the desired version of the attribute information structure to be
386 returned.
387
388
389 mrds_attribute_list_ptr Output pointer
390 is a pointer to the attribute information returned in a structure as
391 described in the Notes below.
392
393
394 error_code Output fixed bin35
395 is the standard status code. It may be one of the following:
396 error_table_$area_too_small
397 if the supplied area could not hold the attribute information.
398 error_table_$badcall
399 if the area_ptr was null.
400 error_table_$unimplemented_version
401 if the structure_version supplied is unknown.
402 mrds_error_$invalid_db_index
403 if the db_index given does not refer to a data base open in this
404 process.
405 mrds_error_$not_freeing_area
406 if the supplied area does not have the attribute "freeing".
407
408
409 mrds_error_$unknown_relation_name
410 if the given relation name is not known in this opening view of
411 the data base.
412 mrds_error_$version_not_supported
413 if the data base referenced is not version 4.
414
415
416 Notes: The only structure version currently available is 1. This
417 entry only works for version 4 data bases.
418
419
420 :Entry: get_opening_temp_dir: 06/17/86 dsl_$get_opening_temp_dir
421
422 Function: This entry returns the pathname of the directory that is
423 being used for temporary storage for a particular data base opening.
424
425
426 Syntax:
427 declare dsl_$get_opening_temp_dir entry
428 fixed bin35 fixed bin35 returnschar168;
429 path = dsl_$get_opening_temp_dirdb_index error_code
430
431
432 Arguments:
433 db_index Input fixed bin35
434 is the integer returned by a call to dsl_$open and refers to the
435 opening whose temporary storage directory is desired.
436 error_code Output fixed bin35
437 is the standard status code. If the supplied db_index does not
438 refer to a currently open data base in the user's process then it
439 will be mrds_error_$invalid_db_index.
440 path Output char168
441 is the absolute pathname of the directory being used for temporary
442 storage for the opening specified.
443
444
445 Notes: See dsl_$get_temp_dir for an entry that will return the
446 directory pathname to be used in the next call to open. Also see
447 dsl_$set_temp_dir and the commands display_mrds_temp_dir and
448 set_mrds_temp_dir.
449
450
451 :Entry: get_path_info: 06/17/86 dsl_$get_path_info
452
453 Function: This entry returns information about a supplied pathname.
454 It indicates whether or not the path refers to a MRDS data base model
455 or submodel, and if so, the version number and details about its
456 creation. This entry replaces dsl_$get_db_version, which is obsolete.
457
458
459 Syntax:
460 declare dsl_$get_path_info entrychar* ptr
461 fixed bin ptr fixed bin35;
462 call dsl_$get_path_infoin_path area_ptr
463 structure_version mrds_path_info_ptr error_code;
464
465
466 Arguments:
467 in_path Input char*
468 is the relative or absolute pathname about which the user desires
469 information. If it refers to a MRDS data base model or submodel, it
470 does not need a suffix, unless ambiguity would result. A model will
471 be found before the submodel if they both have the same name, less
472 suffix, in the same directory.
473 area_ptr Input pointer
474 is a pointer to a user-supplied freeing area in which the path
475 information will be allocated.
476 structure_version Input fixed bin
477 is the desired version of the path information structure to be
478 returned.
479
480
481 mrds_path_info_ptr Output pointer
482 is the pointer to the path information structure that is returned,
483 which is described in the Notes below.
484
485
486 error_code Output fixed bin35
487 is the standard status code. It may be one of the following:
488 error_table_$area_too_small
489 if the supplied area could not hold the path information.
490 error_table_$badcall
491 if the area_ptr was null.
492 error_table_$unimplemented_version
493 if the supplied structure version is unknown.
494 mrds_error_$no_model_access
495 if the user does not have "r" access to the db_model segment
496 under the data base.
497 mrds_error_$no_model_submodel
498 if the path does not refer to a MRDS data base model or submodel.
499 mrds_error_$not_freeing_area
500 if the supplied area does not have the attribute "freeing".
501
502
503 Notes: The only structure version currently available is 1. The
504 variables mrds_path_info_ptr and mrds_path_info_structure_version are
505 also declared in the mrds_path_info include file.
506
507
508 :Entry: get_population: 06/17/86 dsl_$get_population
509
510 Function: This entry returns the current number of tuples in either a
511 permanent or temporary relation.
512
513
514 Syntax:
515 declare dsl_$get_population entry options variable;
516 call dsl_$get_population db_index relation_identifier
517 tuple_count error_code;
518
519
520 Arguments:
521 db_index Input fixed bin35
522 is the integer returned from a call to dsl_$open, which refers to
523 the opening for which population statistics are desired.
524 relation_identifier Input
525 is the identification for the relation whose tuple count is to be
526 returned. If it is declared as character and starts with a letter,
527 then it is interpreted as a permanent relation name. If the string
528 does not start with a letter and it can be converted to a number,
529 then it will be interpreted as a temporary relation index. If the
530 relation identifier is declared as fixed bin 35, then it is
531 interpreted as a temporary relation index.
532 tuple_count Output fixed bin35
533 is the current tuple count for the specified relation in this
534 opening view.
535
536
537 error_code Output fixed bin35
538 is the standard status code. It may be one of the following:
539 mrds_error_$invalid_db_index
540 if the given db_index does not refer to a model or submodel
541 opening of a data base in the user's process.
542 mrds_error_$undef_temp_rel
543 if the temporary relation index given does not refer to a
544 temporary relation currently defined in this opening.
545 mrds_error_$unknown_relation_name
546 if the permanent relation name given is not known in this opening
547 view of the data base.
548
549
550 Notes: This entry can be used to determine the number of tuples
551 selected by a selection expression by defining a temporary relation
552 using that selection expression and calling dsl_$get_population for
553 that temporary relation.
554
555
556 :Entry: get_relation_list: 06/17/86 dsl_$get_relation_list
557
558 Function: This entry returns information about all the relations in
559 the specified opening view.
560
561
562 Syntax:
563 declare dsl_$get_relation_list entry fixed bin35 ptr
564 fixed bin ptr fixed bin35;
565 call dsl_$get_relation_list db_index area_ptr
566 structure_version mrds_relation_list_ptr
567 error_code;
568
569
570 Arguments:
571 db_index Input fixed bin35
572 is the integer returned from a call to dsl_$open, referring to the
573 opening for which relation information is to be returned.
574 area_ptr Input pointer
575 is a pointer to a user-supplied freeing area in which the relation
576 information is to be allocated.
577 structure_version Input fixed bin
578 is the desired version of the relation information structure to be
579 returned.
580 mrds_relation_list_ptr Output pointer
581 is a pointer to the relation information structure that has been
582 allocated and is described in the Notes below.
583
584
585 error_code Output fixed bin35
586 is the standard status code. It may be one of the following:
587 error_table_$area_too_small
588 if the supplied area could not hold the relation information.
589 error_table_$badcall
590 if the area_ptr was null.
591 error_table_$unimplmented_version
592 if the supplied structure version is unknown.
593 mrds_error_$invalid_db_index
594 if the db_index given does not refer to a data base open in this
595 process.
596 mrds_error_$not_freeing_area
597 if the supplied area does not have the attribute "freeing".
598 mrds_error_$version_not_supported
599 if the data base referenced is not version 4.
600
601
602 Notes: Currently, the only structure version available is 1. The
603 variables mrds_relation_list_num_rels_init, mrds_relation_list_ptr, and
604 mrds_relation_list_structure_version are also declared in the
605 mrds_relation_list include file.
606
607
608 :Entry: get_scope: 06/17/86 dsl_$get_scope
609
610 Function: This entry returns the scope currently set on a given
611 relation for the specified opening of the data base.
612
613
614 Syntax:
615 declare dsl_$get_scope entryfixed bin35 char*
616 fixed bin fixed bin fixed bin fixed bin35;
617 call dsl_$get_scopedb_index relation_name
618 permits prevents scope_version error_code;
619
620
621 Arguments:
622 db_index Input fixed bin35
623 is the integer returned from a call to dsl_$open which refers to the
624 opening for which scope information is desired.
625 relation_name Input char*
626 is the name of the relation for which scope information is desired
627 in this opening.
628 permits Output fixed bin
629 is the sum of the scope modes, representing operations that are to
630 be permitted the caller for this relation in this opening. See the
631 table of scope mode encodings in the Notes below.
632 prevents Output fixed bin
633 is the sum of the scope modes representing operations that are to be
634 denied other users of this data base for this relation. See the
635 table of scope mode encodings in the Notes below.
636
637
638 scope_version Output fixed bin
639 if this value is less than five, then the scope mode encoding for
640 the scope represents the old operations of read - store - delete -
641 modify. Otherwise, the scope mode encoding represents the new
642 operations of read_attr, append_tuple, delete_tuple, modify_attr
643 used for attribute level security.
644 error_code Output fixed bin35
645 is the standard status code. It may be one of the following:
646 mrds_error_$scope_not_set
647 if no scope is currently set on the specified relation.
648 mrds_error_$unknown_relation_name
649 if the supplied relation name is not in the opening view
650 specified by db_index.
651
652
653 Notes: The scope modes are encoded using the integer values given
654 below:
655
656
657 Scope
658 Code Operation
659
660 0 null
661 1 read_attr or read
662 2 append_tuple or store
663 4 delete_tuple or delete
664 8 modify_attr or modify
665
666
667 :Entry: get_temp_dir: 06/17/86 dsl_$get_temp_dir
668
669 Function: This entry returns the pathname of the directory that is
670 used for temporary storage upon the next call to dsl_$open.
671
672
673 Syntax:
674 declare dsl_$get_temp_dir entry returns char168;
675 path = dsl_$get_temp_dir
676
677
678 Arguments:
679 path Output char168
680 is the absolute pathname of the directory to be used for temporary
681 storage on the next call to open.
682
683
684 Notes: See dsl_$set_temp_dir and the commands display_mrds_temp_dir
685 and set_mrds_temp_dir.
686
687
688 To obtain the temporary storage directory for a particular opening,
689 call dsl_$get_opening_temp_dir.
690
691
692 :Entry: list_openings: 06/17/86 dsl_$list_openings
693
694 Function: This entry returns information about all openings of MRDS
695 data bases in the user's process. This entry replaces dsl_$list_dbs,
696 which is obsolete.
697
698
699 Syntax:
700 declare dsl_$list_openings entry ptr fixed bin ptr fixed bin35;
701 call dsl_$list_openings area_ptr structure_version
702 mrds_database_openings_ptr error_code;
703
704
705 Arguments:
706 area_ptr Input pointer
707 is a pointer to a user-supplied freeing area in which the opening
708 information will be allocated.
709 structure_version Input fixed bin
710 is the desired version of the structure that is to return opening
711 information.
712 mrds_data base_opening_ptr Output pointer
713 is a pointer to an allocated structure containing the opening
714 information which is described in the Notes below.
715
716
717 error_code Output fixed bin35
718 is a standard status code. It may be one of the following:
719 error_table_$area_too_small
720 if the supplied area could not hold the opening information.
721 error_table_$badcall
722 if the area_ptr was null.
723 error_table_$unimplemented_version
724 if the given structure_version is unknown.
725 mrds_error_$not_freeing_area
726 if the supplied area does not have the attribute "freeing".
727
728
729 Notes: Note that the structure is still allocated and a 0 error code
730 returned even if the total number of open data bases is 0.
731
732
733 :Entry: modify: 06/17/86 dsl_$modify
734
735 Function: This entry allows the user to modify attribute values
736 contained in the tuples of one relation in the data base. The
737 modification of a key attribute is not allowed. The user must have
738 read_write permission to the relation. All selected tuples are
739 modified.
740
741
742 Syntax:
743 declare dsl_$modify entry options variable;
744 call dsl_$modify data_base_index selection_expression se_index
745 se_value1 ... se_valuen modified_value1 ... modified_valuen
746 code;
747
748
749 Arguments:
750 data_base_index Input fixed bin35
751 is the index returned by dsl_$open that designates the data base.
752 selection_expression Input char*
753 is a character string see "Examples of Selection Mechanisms" as
754 defined at the beginning of this section. The select clause can
755 only specify attributes from one relation. This character string
756 may be a constant or a variable declared character varying or
757 non-varying.
758 se_index Input fixed bin35
759 is an integer used to refer to a compiled selection expression. It
760 is required only if the selection expression is "-compiled".
761
762
763 se_valuei Input
764 is a selection expression value for each argument substitution
765 designated by .V. or .X. appearing in the
766 <selection_expression> including temporary relation rel_index
767 designations. These must be specified so as to correspond in order
768 and quantity with the argument substitution specified in the
769 <selection_expression. If the selection expression is "-compiled",
770 then the selection expression value is substituted for the .X.
771 value in the where clause that has to be satisfied. These values
772 are supplied in the order in which they occur in the selection
773 expression used in the call to dsl_$compile. If the specified data
774 type does not equal the attribute data type, the value
775 mrds_error_$inv_data_type is returned in the code.
776
777
778 modified_valuei Input
779 is a modified tuple attribute value that is to replace the current
780 such value in the data base. There must be a one-to-one
781 correspondence between these values and the tuple items specified in
782 the selection expression. If a structure is used for modified tuple
783 attribute values, only one structure may be used. Only data types
784 supported by assign_ may be used for modified tuple attribute
785 values.
786 code Output fixed bin35
787 is a standard status code. A value of 0 indicates that no error
788 occurred. A value of mrds_error_$tuple_not_found indicates that no
789 error occurred and that no data satisfied the selection expression.
790
791
792 Notes: For shared openings, the relation must have modify_attr permit
793 scope set.
794
795
796 For attribute level security, the attributes specified in the select
797 and where clauses must have read_attr access. In addition, the
798 attributes specified in the select clause must have modify_attr access.
799
800
801 :Entry: open: 06/17/86 dsl_$open
802
803 Function: This entry causes the specified data bases to be opened for
804 processing in the designated modes. For each opened data base, an
805 index that is to be used to specify that data base in future MRDS calls
806 is returned. If one or more of the data bases specified cannot be
807 opened for any reason, none of the others are opened.
808
809
810 Syntax:
811 declare dsl_$open entry options variable;
812 call dsl_$open path1 data_base_index1 mode1 ...
813 pathn data_base_indexn moden code;
814
815
816 Arguments:
817 pathi Input char*
818 is a character string containing the absolute or relative pathname
819 of the data submodel or the data base with or without a suffix
820 defining the relevant portion of the data base. If the path of the
821 data base itself is specified, the data model is used in place of
822 the data submodel.
823 data_base_indexi Output fixed bin35
824 is an integer that is to be used in subsequent MRDS calls to specify
825 the corresponding data base designated in this opening.
826
827
828 modei Input fixed bin35
829 is an integer 123or 4 indicating the usage mode for which the
830 data base is to be opened.
831 1 specifies that this is a shared opening, requiring the setting of
832 concurrency control protection via scope requests by the set_scope
833 function. The maximum permit scope that can be set with this
834 opening mode is read_attr.
835 2 specifies that this is a shared opening, requiring the setting of
836 concurrency control protection via scope requests by the set_scope
837 function. Any scope can be set with this opening mode.
838
839
840 3 specifies that this is an unshared opening in the sense that all
841 update operations are prevented against any relations in this view
842 of the data base. No scope setting is necessary with this opening
843 mode. This mode is the equivalent of opening with a retrieval
844 mode and doing a set_scope_all with permit of read_attr and
845 prevents of modify_attr, append_tuple, and delete_tuple on these
846 relations. Other data base openers are allowed to set read_attr
847 scope and to do retrievals in these relations.
848
849
850 4 specifies that this is an unshared opening. No scope setting is
851 necessary with this opening mode. No other data base openers are
852 allowed to set any scope or any relation in this view of the data
853 base. This mode is the equivalent of opening with an update mode
854 and doing a set_scope_all with permits and prevents of read_attr,
855 modify_attr, append_tuple, and delete_tuple on these relations.
856 Only one opening with this mode is allowed if the set of relations
857 in this view overlaps the relations in another opener's view.
858 code Output fixed bin35
859 is a standard status code.
860
861
862 Notes: Open modes 1 and 2 require subsequent calls to the dsl_ entry
863 set_scope. Also see Appendix F for the include file
864 mrds_open_modes_.incl.pl1.
865
866
867 If a data model and submodel of the same name are in the same
868 directory, the model is found if no suffix is given.
869
870
871 If the data base being opened has been secured, then the view_path must
872 refer to a submodel that resides in the "secure.submodels" directory
873 under the data base directory if the user is not a DBA. These must be
874 version 5 submodels if attribute level security is to be provided. See
875 secure_mrds_db.
876
877
878 If the data base being opened uses a version 4 concurrency control,
879 then adjust_mrds_db with the -reset option must be run against it to
880 update it to version 5 concurrency control before it can be opened.
881 This changes the scope modes from r-u, to read_attr, modify_attr,
882 append_tuple, delete_tuple.
883
884
885 Application programs calling dsl_$set_scope, dsl_$set_scope_all, or
886 dsl_$dl_scope making use of r-s-m-d encodings will not be impacted.
887 Those programs using the r-u encodings will have to be changed to the
888 encodings given in this manual.
889
890
891 A maximum of 128 openings of the same or different data bases is
892 allowed. Only 64 of these openings can be version 3 or earlier data
893 bases.
894
895
896 Access requirements for all opening modes includes "r" ACL on the
897 db_model segment and relation model segments these segments have a
898 ".m" suffix for any relations appearing in the given view, plus "rw"
899 ACL on the data base concurrency control segment. Unshared openings
900 require that, for any relation appearing in the view, the multisegment
901 file containing the data must have "r" ACL for exclusive_retrieval or
902 "rw" ACL for exclusive_update opening mode. For attribute level
903 security, exclusive_retrieval mode requires read_attr on some attribute
904 in each relation in the opening view and exclusive_update mode requires
905 one of append_tuple on the relation, delete_tuple on the relation, or
906 modify_attr on some attribute in the relation, for each of the
907 relations in the opening view.
908
909
910 :Entry: retrieve: 06/17/86 dsl_$retrieve
911
912 Function: This entry allows the user to retrieve selected attribute
913 values from the data base. The user must have read permission to the
914 referenced relations. One tuple per call is returned.
915
916
917 Syntax:
918 declare dsl_$retrieve entry options variable;
919 call dsl_$retrieve data_base_index selection_expression se_index
920 se_value1 ... se_valuen value1 ... valuen code;
921
922
923 Arguments:
924 data_base_index Input fixed bin35
925 is the index returned by dsl_$open that designates the data base.
926
927
928 selection_expression Input char*
929 is a character string see "Formal Definition of the Selection
930 Expression" in this section. This character string may be a
931 constant or a variable declared character varying or nonvarying. If
932 the expression results in the selection of identical tuples, only
933 one copy is returned unless the -dup option is specified. However,
934 all tuples selected remain available for retrieval with additional
935 calls to dsl_$retrieve with a <selection_expression> consisting of
936 "-another". They cease to be available whenever any dsl_ entry is
937 called with a <selection_expression> consisting of an
938 <alpha_expression>. The selection expression "-another" does not
939 return duplicate tuples unless the -dup option was specified in the
940 original <alpha_expression>. The -dup option cannot be used with
941 set operations. The range clause may have a ".V." for substitution
942 of a temporary relation's rel_index.
943
944
945 se_index Input fixed bin35
946 is an integer used to refer to a compiled selection expression. It
947 is required only if the selection expression is "-compiled".
948
949
950 se_valuei Input
951 is a selection expression value for each argument substitution
952 designated by .V. or .X. appearing in the
953 <selection_expression>, including temporary relation rel_index
954 designations. These must be specified so as to correspond in order
955 and quantity with the argument substitution specified in the
956 <selection_expression). If the selection expression is "-compiled",
957 then the selection expression value is substituted for the .X.
958 value in the where clause that has to be satisfied. These values
959 are supplied in the order in which they occur in the selection
960 expression used in the call to dsl_$compile. If the specified data
961 type does not equal the attribute data type, the value
962 mrds_error_$inv_data_type is returned in the code.
963
964
965 valuei Output
966 is a retrieved attribute value. The value may be a structure only
967 one regardless of the number of relations or a list of individual
968 values, the items of which must correspond in order and quantity
969 with the tuple items specified in the <selection_expression>. If an
970 entire tuple is retrieved by specifying only the tuple_value in the
971 select clause, then a value must be specified for every attribute of
972 the corresponding relation as defined in the data submodel or in the
973 data model, whichever is being used. If data conversion is
974 required, only data types supported by assign_ may be used.
975
976
977 code Output fixed bin35
978 is a standard status code. A value of 0 indicates that no error
979 occurred and that one occurrence of the specified data has been
980 successfully retrieved. A value of mrds_error_$tuple_not_found
981 indicates that no error occurred and that no data satisfied the
982 selection expression.
983
984
985 Notes: For shared openings, the referenced relations must have
986 read_attr permit scope set.
987
988
989 For attribute level security, attributes referenced in the select and
990 where clauses must have read_attr access.
991
992
993 :Entry: set_scope: 12/01/86 dsl_$set_scope
994
995 Function: This entry defines the user's current scope of access to the
996 data base for shared modes of openings.
997
998
999 Syntax:
1000 declare dsl_$set_scope entry options variable;
1001 call dsl_$set_scope db_index rel_name1 permit_ops1 prevent_ops1
1002 ... rel_namen permit_opsn prevent_opsn wait_sec code;
1003
1004
1005 Arguments:
1006 db_index Input fixed bin35
1007 is the index returned by dsl_$open that designates the data base.
1008 rel_namei Input char*
1009 is the name of the relation to be included in the scope.
1010 permit_opsi Input fixed bin
1011 is an integer consisting of the scope code which indicates the
1012 operations the user may perform on the relation.
1013 prevent_opsi Input fixed bin
1014 is an integer consisting of the scope code which indicates the
1015 operations that other users may not perform on the relation.
1016
1017
1018 wait_sec Input fixed bin35
1019 specifies the maximum number of seconds to wait for the scope
1020 request to be honored there is no anticipated maximum. This
1021 argument is optional and if not provided by the user, the default is
1022 30 seconds.
1023 code Output fixed bin35
1024 is a standard status code. The code is 0 if set_scope is successful
1025 or is mrds_error_$db_busy if the data base is busy.
1026
1027
1028 Notes: Before a user can access the data base in shared mode, a scope
1029 of access must be declared, consisting of a set of scope tuples. If
1030 this scope does not conflict with any other currently existing scope
1031 of other processes, it is accepted. Otherwise, the user's request is
1032 placed in a queue and is processed as soon as the requested resources
1033 become available. If the specified wait time is exceeded before the
1034 request can be processed, an error code is returned. Once the scope
1035 has been accepted, only operations permitted by the scope may be
1036 performed. As time progresses in the current process, individual scope
1037 tuples may be removed as they are no longer needed by invoking
1038 dsl_$dl_scope. However, new tuples may not be added to the current
1039 scope until all current scope has been deleted. This rule avoids
1040 potential deadlock problems within the data base manager.
1041
1042
1043 Codes for operations to be prevented or permitted are;
1044
1045 Scope
1046 Code Operation
1047
1048 0 null
1049 1 read_attr or read
1050 2 append_tuple or store
1051 4 delete_tuple or delete
1052 8 modify_attr or modify
1053
1054
1055 :Entry: set_scope_all: 12/01/86 dsl_$set_scope_all
1056
1057 Function: This entry provides a means of setting a scope on all
1058 relations defined in the user's view without the need to name each
1059 relation. Identical permit operations and prevent operations are
1060 applied to all the relations in the user's view.
1061
1062
1063 Syntax:
1064 declare dsl_$set_scope_all entry options variable;
1065 call dsl_$set_scope_all db_index permit_ops prevent_ops wait_sec
1066 code;
1067
1068
1069 Arguments:
1070 db_index Input fixed bin35
1071 is the index returned by dsl_$open that designates the data base.
1072 permit_ops Input fixed bin
1073 is the scope code which indicates the operations the user may
1074 perform on the relation.
1075 prevent_ops Input fixed bin
1076 is the scope code which indicates the operations that other users
1077 may not perform on the relation.
1078 wait_sec Input fixed bin35
1079 specifies the maximum number of seconds to wait for the scope
1080 request to be honored there is no anticipated maximum. This
1081 argument is optional and, if not provided by the user, the default
1082 is 30 seconds.
1083
1084
1085 code Output fixed bin35
1086 is a standard status code.
1087
1088
1089 Notes: Scope codes for operations to be prevented or permitted are:
1090
1091 Scope
1092 Code Operation
1093
1094 0 null
1095 1 read_attr or read
1096 2 append_tuple or store
1097 4 delete_tuple or delete
1098 8 modify_attr or modify
1099
1100
1101 See dsl_$set_scope for access requirements.
1102
1103
1104 :Entry: set_temp_dir: 12/01/86 dsl_$set_temp_dir
1105
1106 Function: This entry sets the directory that is used for temporary
1107 storage on the next call to dsl_$open.
1108
1109
1110 Syntax:
1111 declare dsl_$set_temp_dir entry char* fixed bin35;
1112 call dsl_$set_temp_dir path code;
1113
1114
1115 Arguments:
1116 path Input char*
1117 is the relative or absolute pathname of the directory to be used for
1118 temporary storage on the next call to open.
1119 code Output fixed bin35
1120 is the standard status code and is 0 unless an error occurs.
1121
1122
1123 Notes: This temporary directory has a default of process directory.
1124 Therefore, this entry need never be called unless a record quota
1125 overflow occurs on the process directory, as might happen in opening a
1126 data base with a large number of relations, or during a large retrieve
1127 or define_temp_rel operation.
1128
1129
1130 See dsl_$set_temp_dir, dsl_$get_temp_dir, dsl_$get_opening_temp_dir,
1131 and the commands display_mrds_temp_dir and set_mrds_temp_dir.
1132
1133
1134 :Entry: store: 06/17/86 dsl_$store
1135
1136 Function: This entry allows the user to add a tuple to a designated
1137 relation in the data base.
1138
1139
1140 Syntax:
1141 declare dsl_$store entry options variable;
1142 call dsl_$store data_base_index relation_expression
1143 new_value1 ... new_valuen code;
1144
1145
1146 Arguments:
1147 data_base_index Input fixed bin35
1148 is the index returned by dsl_$open that designates the data base.
1149 relation_expression Input char*
1150 indicates the relation to which the tuple is to be added, as it
1151 appears in the user's view of the data base the data model or the
1152 data submodel. It may be the name of the relation or it may be
1153 "-another".
1154 new_valuei Input
1155 is the new tuple value to be added to the relation. The entire
1156 tuple, as defined in the user's view, may be specified with one
1157 structure or a list of variables, the items of which must correspond
1158 in order and quantity with the attributes defined in the user's
1159 view.
1160
1161
1162 code Output fixed bin35
1163 is a standard status code. The value is 0 if the store was
1164 successful. If a duplicate of the primary key already exists in the
1165 data base, the code value mrds_error_$dup_store is returned and the
1166 tuple is not stored. The name mrds_error_$duplicate_key may also
1167 be used. If a -check_proc option exists on a domain of one of the
1168 attributes in the relation for which a tuple is being added and the
1169 check procedure returns false, then the error code,
1170 mrds_error_$dom_integ, is returned.
1171
1172
1173 Notes: The placement of the new tuple within the relation is
1174 determined by MRDS, based upon data model/data submodel descriptions of
1175 the data base and the value of the primary key in the new tuple. The
1176 primary key of the new tuple must be unique within the designated
1177 relation. The caller must have read-write permission to the relation.
1178 If storing through a submodel view, all attributes of the relation must
1179 be defined in the submodel.
1180
1181
1182 If the relation_expression is the name of a relation, the new tuple is
1183 added to the named relation. If the relation_expression is "-another",
1184 the new tuple is added to the relation specified in the most recent
1185 call to the dsl_$store in which the relation_expression argument
1186 consisted of a relation name. Any call to a dsl entry requiring a
1187 <selection_expression> causes the previously specified relation name to
1188 become unavailable for subsequent reference using "-another", until it
1189 is again established via a call to dsl_$store with a
1190 relation_expression consisting of the relation name.
1191
1192
1193 The use of "-another" provides an efficient means to store several
1194 tuples into a single relation via consecutive dsl_$store calls.
1195
1196
1197 For shared openings, the relation must have append_tuple permit scope
1198 set.
1199
1200
1201 For attribute level security, the relation must have append_tuple
1202 access and the key attributes must have read_attr access.