View source for $DGBLSC

'''$DGBLSC''', or '''Delete Global Section''', is a [[System Service|system service]] that marks an existing permanent global section for deletion.

=Description=
The Delete Global Section service marks an existing permanent global section for deletion. The actual deletion of the global section takes place when all processes that have mapped the global section have deleted the mapped pages.

After a global section has been marked for deletion, any process that attempts to map it receives the warning return status code SS$_NOSUCHSEC.

Temporary global sections are automatically deleted when the count of processes
using the section goes to 0.

On VAX systems, a section located in memory that is shared by multiple processors can be marked for deletion only by a process running on the same processor that created the section.

The $DGBLSC service does not unmap a global section from a process’s virtual
address space. To do this, the process should call the Delete Virtual Address
Space ($DELTVA or $DELTVA_64) service, which deletes the pages to which the
section is mapped.

=Syntax=
 <nowiki>SYS$DGBLSC [</nowiki>[[#flags|flags]]<nowiki>] ,</nowiki>[[#gsdnam|gdsnam]]<nowiki> ,[</nowiki>[[#ident|ident]]<nowiki>]</nowiki>

C prototype:
 int sys$dgblsc (unsigned int flags, void *gsdnam, struct _secid *ident);

=Arguments=

==flags==
{{SyservArgument|mask_longword|longword (unsigned)|read only|by value}}

Mask indicating global section characteristics. The flags argument is a longword value. A value of 0 (the default) specifies a group global section; a value of SEC$M_SYSGBL specifies a system global section; a value of SEC$M_SHMGS on an OpenVMS Galaxy system creates a shared-memory global section.

==gdsnam==
{{SyservArgument|section_name|character-coded text string|read only|by descriptor-fixed-length string descriptor}}

Name of the global section to be deleted. The '''gsdnam''' argument is the address
of a character string descriptor pointing to this name string.

For group global sections, the operating system interprets the group UIC as part of the global section name; thus, the names of global sections are unique to UIC groups.

You can specify any name from 1 to 43 characters. All processes mapping to the
same global section must specify the same name. Note that the name is case
sensitive.

Use of characters valid in logical names is strongly encouraged. Valid values
include alphanumeric characters, the dollar sign ($), and the underscore (_). If the name string begins with an underscore (_), the underscore is stripped and the resultant string is considered to be the actual name. Use of the colon (:) is not permitted.

Names are first subject to a logical name translation, after the application of the prefix GBL$ to the name. If the result translates, it is used as the name of the section. If the resulting name does not translate, the name specified by the caller is used as the name of the section.

See [https://support.hpe.com/hpsc/doc/public/display?docId=emr_na-c04621447 OpenVMS Programming Concepts Manual] for more information on logical name translations and section name procesing.

==ident==
{{SyservArgument|section_id|quadword (unsigned)|read only|by reference}}

Identification value specifying the version number of the global section to be
deleted and the matching criteria to be applied. The ident argument is the 32- or 64-bit address (on Alpha and I64 systems) or the 32-bit address (on VAX systems) of a quadword structure containing three fields.

The version number is in the second longword. The version number contains two
fields: a minor identification in the low-order 24 bits and a major identification in the high-order 8 bits. Values for these fields can be assigned by installation convention to differentiate versions of global sections. If you specify no version number when creating a section, processes that specify a version number when mapping cannot access the global section.
The first longword specifies, in its low-order 3 bits, the matching criteria. The valid values, the symbolic names by which they can be specified, and their
meanings are listed in the following table:

{| class="wikitable"
! colspan="col" | Value
! colspan="col" | Name
! colspan="col" | Match Criteria
|-
| 0
| SEC$K_MATALL 
| Match all versions of the section
|-
| 1 
| SEC$K_MATEQU 
| Match only if major and minor identifications match.
|-
| 2 
| SEC$K_MATLEQ 
| Match if the major identifications are equal and the minor identification of the mapper is less than or equal to the minor identification of the global section
|}

If you specify no address or specify it as 0 (the default), the version number and match control fields default to 0.

=Condition Values Returned=

{| class="wikitable"
! colspan="col" | Value
! colspan="col" | Description
|-
| SS$_NORMAL 
| The service completed successfully.
|-
| SS$_ACCVIO 
| The global section name or name descriptor or the section identification  field cannot be read by the caller.
|-
| SS$_INTERLOCK 
| The bit map lock for allocating global sections from the specified shared memory is locked by another process.
|- 
| SS$_IVLOGNAM
| The global section name has a length of 0 or has more than 15 characters.
|-
| SS$_IVSECFLG 
| You set an invalid flag, reserved flag, or flag requiring a user privilege.
|-
| SS$_IVSECIDCTL 
| The section identification match control field is invalid.
|-
| SS$_NOPRIV 
| The caller does not have the privilege to delete a system global section, does not have read/write access to a group global section, or does not have the privilege to delete a global section located in memory that is shared by multiple processors.
|-
| SS$_NOSUCHSEC 
| The specified global section does not exist, or the identifications do not match.
|-
| SS$_NOTCREATOR 
| The section is in memory shared by multiple processors and was created by a process on another processor.
|-
| SS$_SHMNOTCNCT ([[VAX]] specific) 
| The shared memory named in the name argument is not known to the system. This
error can be caused by a spelling error in the string, an improperly assigned logical name, or the failure to identify the multiport memory as shared at system generation time.
|-
| SS$_TOOMANYLNAM 
| The logical name translation of the gsdnam string exceeded the allowed depth of 10.
|}

=Required Access or Privileges=
Depending on the operation, the calling process might need one or more of the
following privileges:
* [[SYSGBL]] privilege to delete a system global section
* [[PRMGBL]] privilege to delete a permanent global section
* [[PFNMAP]] privilege to delete a page frame section
* [[SHMEM]] privilege to delete a global section located in memory shared by
multiple processors

=Required Quota=
None

=See also=
* [[$ADJSTK]]
* [[$ADJWSL]]
* [[$CRETVA]]
* [[$CRMPSC]]
* [[$DELTVA]]
* [[$EXPREG]]
* [[$LCKPAG]]
* [[$LKWSET]]
* [[$MGBLSC]]
* [[$PURGWS]]
* [[$SETPRT]]
* [[$SETSTK]]
* [[$SETSWM]]
* [[$ULKPAG]]
* [[$ULWSET]]
* [[$UPDSEC]]
* [[$UPDSECW]]