The published literature is an essential component of any scientific endeavor, not just in molecular biology. The bibliographic component of the specification and the tools which go with it may find wide use then, permitting reuse of software and databases in many contexts. In addition, the fact that bibliographic citations appear in data from many sources, makes this data extremely valuable in linking data items from different databases to each other (i.e. indirectly through a shared literature citation) to build integrated views of complex data. For this reason, it is also important that database builders ensure that their literature component contain sufficient information to permit this mapping. By conforming to the specification below one can be assured that this will be the case.
Much of the following bibliographic specification was derived from the components recommended in the American National Standard for Bibliographic References (ANSI Z39.29-1977), and in interviews with professional librarians at the National Library of Medicine. The recommendations were then relaxed somewhat (by making certain fields OPTIONAL) to accommodate the less complete citation information available in current biomedical databases. Thus, although a field may be OPTIONAL, a database builder should still attempt to fill it, if it can reasonably be done.
In this chapter we also present a specification for the base class Pub, publications of any sort and collections of publications. The MEDLINE specification has enough unique components that it is discussed separately in another chapter.
Affiliation is effectively the institutional affiliation of an author. Since it has the same fields needed to cite a publisher (of a book) it is reused in that context as well, although in that case it is not precisely an "affiliation". Affil is a CHOICE of two forms, a structured form which is preferred, or an unstructured string when that is all that is available.
The structured form has a number of fields taken from the ANSI guidelines. "affil" is institutional affiliation, such as "Harvard University". "div" is division within institution, such as "Department of Molecular Biology". "city" is obvious. "sub" is a subdivision of a country. In the United States, this would be the state. "country" is obvious. "street" has been added to the specification (it is not included in ANSI) so that it is possible to produce a valid mailing address.
Auth-list is the list of authors for the citation. It is a SEQUENCE, not a SET, since the order of author names matters. The names can be unstructured strings (the least desirable), semi-structured strings following the MEDLINE rules (e.g. "Jones JM"), or fully structured Authors (most desirable). An Affil can be associated with the whole list (typical of a scientific article). A more detailed discussion on the use of different types of names can be found in the "Identifying People" section of the "General Use Objects" chapter.
If fully structured Authors are used, each Author can have an individual Affil. The Author uses Person-id (defined in general.asn) which can be an unstructured string or MEDLINE string, as above, or a fielded name with the components broken out separately. The Author form also allows specification of the role of individual authors in producing the citation. The primary author(s) does not mean the "first" author, but rather that this author had a role in the original writing or experimental work. A secondary author is a reviewer or editor of the article. It is rare in a scientific work that a secondary author is ever mentioned by name. Authors may play different roles in the work., compiling, editing, translating. Again, in a scientific work, the authors mentioned did none of these things, but were involved in the actual writing of the paper, although it would not be unusual anymore for one author to be the patent assignee. For scientific work, then, the main advantages of using the Author form is the use of fielded names and of individual Affils. For a book, being able to indicate the editors vs. the authors is useful also.
Imprint provides information about the physical form in which the citation appeared, such as what volume and issue of a journal it was in. For the "date" a structured Date is preferred. While "volume", "issue", and "pages" are commonly integers, there are many cases where they are not pure integers (e.g. pages xvi-xvii or issue 10A). Pages is given as a single string to simplify input from different sources. The convention is first page (hyphen) last page, or just page if it is on a single page. "section" may be relevant to a book or proceedings. "pub" is an Affil used to give the publisher of a book. The Affil.affil field is used to give the name of the publisher. "cprt" is the copyright date for a book. "part-sup" is for part or supplement and is not part of ANSI, but is used by MEDLINE. "language" is for the original language of the publication, which is also used by MEDLINE, but is not part of the ANSI standard. "prepub" is not part of the ANSI standard, but was added by NCBI to accommodate citations for as yet unpublished papers that can accompany data directly submitted by authors to the database.
A published work may have a number of Titles, each playing a particular role in specifying the work. There is the title of a paper, the title of a book it appears in, or the title of the journal, in which case it may come from a controlled list of serials. There may also be an original title and a translated title. For these reasons, Title is a defined entity rather than just a string, to allow the roles to be specified explicitly. Certain types of Title are legal for an Article, but not for a Journal or a Book. Rather than make three overlapping definitions, one for Article Titles, one for Journal Titles, and one for Book Titles, we have made one Title type and just indicated in the comments of the specification whether a particular form of Title is legal for an Article, Journal, or Book. Title is a SET OF because a work may have more than one title (e.g. an original and a translated title, or an ISO journal title abbreviation and an ISSN).
Title can be of a number of types. "name" is the full title of an article, or the full name of a book or journal. "tsub" is a subordinate title (e.g. "Hemoglobin Binds Oxygen" might be a primary title, while "Heme Groups in Biology: Part II" might be a subordinate title). "trans" is the translated title. So for an English language database like MEDLINE which contains an article originally published in French, the French title is "name" and the English version of it is "trans".
"jta" is a journal title abbreviation. It is only valid for a journal name, obviously. "jta" does not specify what kind of abbreviation it is, so it is the least useful of the journal designations available and should only be used as a last resort. "iso-jta" is an International Standards Organization (ISO) journal title abbreviation. This is the preferred form. A list of valid iso-jta's is available from NCBI or the National Library of Medicine. "ml-jta" is a MEDLINE journal title abbreviation. MEDLINE pre-dates the ISO effort, so it does not use iso-jta's. "coden" is a six letter code for journals which is used by a number of groups, particularly in Europe. "issn" is a code used by publishers to identify journals. To facilitate the use of controlled vocabularies for journal titles, NCBI maintains a file of mappings between "name", "iso-jta", "ml-jta", "coden", and "issn" where it is possible, and this file is available upon request.
"abr" is strictly the abbreviated title of a book. "isbn" is similar to "issn" in that it is a publishers abbreviation for a book. "isbn" is very useful, but one must be careful since it is used by publishers to list books, and to a publisher a hard cover book is different from a paperback (and get different "isbn"s) even if they are the same title.
An article always occurs within some other published medium. It can be an article in a journal or a chapter or section in a book or proceedings. Thus there are two components to an article citation; a citation for the work it was published in and a citation for the article within that work. Cit-art.title is the Title of the article and Cit-art.authors are the authors of the article. The "from" field is used to indicate the medium the article was published in, and reuses the standard definitions for citing a journal, book, or proceedings.
In the C structure, CitArt.from gives the type of medium published in, and CitArt.fromptr must be cast appropriately to CitJourPtr or CitBookPtr (proceedings uses the same structure as book).
Cit-jour is used to cite an issue of a journal, not an article within a journal (see Cit-art, above). Cit-jour.title is the title of the journal, and Cit-jour.imp gives the date, volume, issue of the journal. Cit-jour.imp also gives the pages of an article within the issue when used as part of a Cit-art. This is not the purest possible split between article and journal, book, or proceedings, but does have the practical advantage of putting all such physical medium information together in a single common data structure. A controlled list of journal titles is maintained by NCBI, and database builders are encouraged to use this list to facilitate exchange and linking of data between databases.
Cit-book is used to cite a whole book, not an article within a book (see Cit-art, above). Cit-book.title is the title of this particular book. Cit-book.coll is used if the book if part of a collection, or muti-volume set (e.g. "The Complete Works of Charles Darwin"). Cit-book.authors is for the authors or editors of the book itself (not necessarily of any particular chapter). Cit-book.imp contains the publication information about the book. As with a Cit-art, if the Cit-book is being used to cite a chapter in a book, the pages in given in Cit-book.imp.
In the C structure, CitBook is used for Cit-book, Cit-proc, and Cit-let, since they have most fields in common. If CitBook.othertype is 0, it is just a Cit-book.
A proceedings is a book published as a result or byproduct of a meeting. As such it contains all the same fields as a Cit-book and an additional block of information describing the meeting. These extra fields are the meeting number (as a string to accommodate things like "10A"), the date the meeting occurred, and an OPTIONAL Affil to record the place of the meeting. The name of the organization or meeting is normally the book title. Don't be confused by things like the Proceedings of the National Academy of Sciences, USA, which is really a journal.
In the C structure, a CitBook is used, with CitBook.othertype set to 1. CitBook.otherdata contains a ValNodePtr. The proceedings can have up to 3 ValNodes where the ValNode.choice indicates the component of the Meeting information, and ValNode.data.ptrvalue contains a pointer to the appropriate data as below:
* choice ASN.1 field Pointer type * 1 number CharPtr * 2 date DatePtr * 3 place AffilPtr
There are separate CitProcAsnRead() and CitProcAsnWrite() functions. A proceedings reuses the parent class CitBookNew() and CitBookFree() functions.
A letter, manuscript, or a thesis share most components and so are grouped together under Citlet. They all require most of the attributes of a book, and thus Citlet incorporates the Citbook structure. Unlike a normal book, they will not have a copyright date. A letter or manuscript will not have a publisher, although a thesis may. In addition, a manuscript may have a manuscript identifier (e.g. "Technical Report X1134").
The CitBook C structure is reused for Citlet. The CitBook.othertype is 2. CitBook.let_type is used to indicate if it is a letter, manuscript, or thesis. If it is a manuscript, then CitBook.otherdata is a CharPtr which may be NULL, or point to a string with the manuscript-id.
This form is used to cite the submission of data directly to a database, independent of any publication(s) which may be associated with the data as well. Authors (of the submission) and Date (in an Imprint) are required. The Affiliation of the Authors should be filled in the Author-list. Optionally one may also record the medium in which the submission was made.
A full patent citation, Cit-pat conveys not only enough information to identify a patent (see below) but to characterize it somewhat as well. A patent has a title and authors, the country in which the patent was issued, a document type and number, and the date the patent was issued. Patents are grouped into classes based on the patent subject, and this may be useful to know. In addition, when a patent is first filed it is issued an application number (different from the document number assigned to the issued patent). For tracking purposes, or issues of precedence, it is also helpful to know the application number and filing date.
The C structure, CitPat, is a straightforward mapping of the Cit-pat fields.
When citing a patent, it may be sufficient to merely unambiguously identify it, on the assumption that more extensive information will be available from some other source, given the identifier. Id-pat thus contains fields only for the country in which the patent was applied for, or issued in, then a CHOICE of the patent document number (if issued) or the application number (if pending).
The C structure, IdPat, is a straightforward mapping the Id-pat fields.
A number of the fields in Cit-art and Cit-book are OPTIONAL, not only to allow incorporation of older, incomplete databases, but also to allow partial information for works submitted, or in press. One simply fills in as many of the fields in Cit-art or Cit-book as possible. One must also set the "pre-pub" flag in Imprint to the appropriate status. That's it. Once the work is published, the remaining information is filled in and the "pre-pub" flag is removed. NOTE: this does NOT apply to work which is "unpublished" or "personal communication", or even "in preparation" because one knows nothing about where or when (or if) it will ever be published. One must use a Cit-gen for this (below).
A generic citation, Cit-gen, is used to hold anything not fitting into the more usual bibliographic entities described above. Cit-gen.cit is a string which can hold a unparsable citation (if you can parse it into a structured type, you should). Sometimes it possible to parse some things but not everything. In this case, a number of fields, such as authors, journal, etc., which are similar to those in the structured types, can be populated as much as possible, and the remainder of the unparsed string can go in "cit".
Less standard citation types, such as a MEDLINE unique identifier, or the serial numbers used in the GenBank flatfile can be accommodated by Cit-gen. An unpublished citation normally has authors and date filled into the structured fields. Often a title is available as well (e.g. for a talk or for a manuscript in preparation). The string "unpublished" can then appear in the "cit" field.
Software developed to display or print a Cit-gen must be opportunistic about using whatever information is available. Obviously it is not possible to assume that all Cit-gens can be displayed in a uniform manner, but in practice at NCBI we have found they can generally be made fairly regular.
A Pub is the bibliographic object base class. It can accommodate a citation of any kind defined in the bibliographic specification, the MEDLINE specification, and more. It is very useful when one wishes to be able to associate a bibliographic reference in a very general way with a software tool or data item, yet still preserve the attributes specific for each class of citation. Pub is widely used for this purpose in the NCBI specifications.
The C structures implement a Pub as a ValNode, where the choice gives the publication type and, in most cases, data.ptrvalue is a pointer to the appropriate data structure (and must be cast to the appropriate type for further use). The exception is for MEDLINE uid, which uses the data.intvalue field. The values are listed in objpub.h.
In some cases a database builder may wish to present more than one form of citation for the same bibliographic work. For example, in a sequence entry from the NCBI Backbone database, it is useful to provide the MEDLINE uid (for use as a link by other software tools), the Cit-art (for display to the user), and a Cit-gen containing the internal NCBI Backbone identifier for this publication as the string "pub_id = 188824" (for use in checking the database by in-house staff) for the same article. The Pub-equiv provides this capacity. It is a SET OF Pub. Each element in the SET is an equivalent citation for the same bibliographic work. Software can examine the SET and select the form most appropriate to the job at hand.
A Pub-equiv is implemented as a linked list of ValNodes, where each ValNode is a Pub as described above. NOTE: a Pub of type Pub-equiv is a ValNode whose choice indicates pub-equiv and whose data.ptrvalue is the head of the linked list of ValNodes.
One often needs to collect a set of citations together. Unlike the Pub-equiv (above), a Pub-set is a set of citations for DIFFERENT bibliographic works. It is a CHOICE of types for a mixture of publication classes, or for a collection of the same publication class.
A Pub-set is implemented as a ValNode, where the choice gives the type of the Pub-set and data.ptrvalue points to a linked list of ValNodes. The ValNodes are necessary to create the linked list. For convenience then, the choice of each ValNode is set appropriately for the type of bibliographic object it holds. This is only technically necessary for Pub-set of type "pub", but since it costs nothing all classes of Pub-set are done the same way.
Common question is whether two citations refer to same the publication. Note that this does not necessarily mean they are identical. For example a Medline-entry may refer to the same article as a Cit-art or a simple MEDLINE uid type of Pub. A series of xxxMatch() functions make this determination. Like strcmp() they return 0 if the two arguments refer to the same publication, 1 if the second argument comes after the first, or -1 if the first argument comes after the second. When possible, the ordering is based on some rational attribute of that Pub type, such as MEDLINE uid order. However, particularly when comparing different types of Pubs, the ordering is arbitrary, but unique. Thus the xxxMatch() functions can be used to sort various kinds of Pubs in the same list, or to locate Pubs in such an ordered list by binary search.
The most general function is PubMatch(a,b), which compares two Pubs of any type. PubEquivMatch(a,b) compares two PubEquivs only, CitArtMatch(a,b) compares two CitArts only, and so on.
--$Revision: 2.0 $
--****************************************************************
--
-- NCBI Bibliographic data elements
-- by James Ostell, 1990
--
-- Taken from the American National Standard for
-- Bibliographic References
-- ANSI Z39.29-1977
--
--****************************************************************
NCBI-Biblio DEFINITIONS ::=
BEGIN
EXPORTS Cit-art, Cit-jour, Cit-book, Cit-pat, Cit-let, Id-pat, Cit-gen,
Cit-proc, Cit-sub;
IMPORTS Person-id, Date FROM NCBI-General;
-- Citation Types
Cit-art ::= SEQUENCE { -- article in journal or book
title Title OPTIONAL , -- title of paper (ANSI requires)
authors Auth-list OPTIONAL , -- authors (ANSI requires)
from CHOICE { -- journal or book
journal Cit-jour ,
book Cit-book ,
proc Cit-proc } }
Cit-jour ::= SEQUENCE { -- Journal citation
title Title , -- title of journal
imp Imprint }
Cit-book ::= SEQUENCE { -- Book citation
title Title , -- Title of book
coll Title OPTIONAL , -- part of a collection
authors Auth-list, -- authors
imp Imprint }
Cit-proc ::= SEQUENCE { -- Meeting proceedings
book Cit-book , -- citation to meeting
meet Meeting } -- time and location of meeting
Cit-pat ::= SEQUENCE { -- patent citation
title VisibleString ,
authors Auth-list, -- authors
country VisibleString , -- Patent Document Country
doc-type VisibleString , -- Patent Document Type
number VisibleString , -- Patent Document Number
date-issue Date , -- Patent-Issue Date
class VisibleString OPTIONAL , -- Patent Doc Class Code
app-number VisibleString OPTIONAL , -- Patent Doc Appl Number
app-date Date OPTIONAL } -- Patent Appl File Date
Id-pat ::= SEQUENCE { -- just to identify a patent
country VisibleString , -- Patent Document Country
id CHOICE {
number VisibleString , -- Patent Document Number
app-number VisibleString } } -- Patent Doc Appl Number
Cit-let ::= SEQUENCE { -- letter, thesis, or manuscript
cit Cit-book , -- same fields as a book
man-id VisibleString OPTIONAL , -- Manuscript identifier
type ENUMERATED {
manuscript (1) ,
letter (2) ,
thesis (3) } OPTIONAL }
-- NOTE: this is just to cite a
-- direct data submission, see NCBI-Submit
-- for the form of a sequence submission
Cit-sub ::= SEQUENCE { -- citation for a direct submission
authors Auth-list , -- not necessarily authors of the paper
imp Imprint ,
medium ENUMERATED { -- medium of submission
paper (1) ,
tape (2) ,
floppy (3) ,
email (4) ,
other (255) } OPTIONAL }
Cit-gen ::= SEQUENCE { -- NOT from ANSI, this is a catchall
cit VisibleString OPTIONAL , -- anything, not parsable
authors Auth-list OPTIONAL ,
muid INTEGER OPTIONAL , -- medline uid
journal Title OPTIONAL ,
volume VisibleString OPTIONAL ,
issue VisibleString OPTIONAL ,
pages VisibleString OPTIONAL ,
date Date OPTIONAL ,
serial-number INTEGER OPTIONAL , -- for GenBank style references
title VisibleString OPTIONAL } -- eg. cit="unpublished",title="title"
-- Authorship Group
Auth-list ::= SEQUENCE {
names CHOICE {
std SEQUENCE OF Author , -- full citations
ml SEQUENCE OF VisibleString , -- MEDLINE, semi-structured
str SEQUENCE OF VisibleString } , -- free for all
affil Affil OPTIONAL } -- author affiliation
Author ::= SEQUENCE {
name Person-id , -- Author, Primary or Secondary
level ENUMERATED {
primary (1),
secondary (2) } OPTIONAL ,
role ENUMERATED { -- Author Role Indicator
compiler (1),
editor (2),
patent-assignee (3),
translator (4) } OPTIONAL ,
affil Affil OPTIONAL ,
is-corr BOOLEAN OPTIONAL } -- TRUE if corressponding author
Affil ::= CHOICE {
str VisibleString , -- unparsed string
std SEQUENCE { -- std representation
affil VisibleString OPTIONAL , -- Author Affiliation, Name
div VisibleString OPTIONAL , -- Author Affiliation, Division
city VisibleString OPTIONAL , -- Author Affiliation, City
sub VisibleString OPTIONAL , -- Author Affiliation, County Sub
country VisibleString OPTIONAL , -- Author Affiliation, Country
street VisibleString OPTIONAL }} -- street address, not ANSI
-- Title Group
-- Valid for = A = Analytic (Cit-art)
-- J = Journals (Cit-jour)
-- B = Book (Cit-book)
-- Valid for:
Title ::= SET OF CHOICE {
name VisibleString , -- Title, Anal,Coll,Mono AJB
tsub VisibleString , -- Title, Subordinate A B
trans VisibleString , -- Title, Translated AJB
jta VisibleString , -- Title, Abbreviated J
iso-jta VisibleString , -- specifically ISO jta J
ml-jta VisibleString , -- specifically MEDLINE jta J
coden VisibleString , -- a coden J
issn VisibleString , -- ISSN J
abr VisibleString , -- Title, Abbreviated B
isbn VisibleString } -- ISBN B
Imprint ::= SEQUENCE { -- Imprint group
date Date , -- date of publication
volume VisibleString OPTIONAL ,
issue VisibleString OPTIONAL ,
pages VisibleString OPTIONAL ,
section VisibleString OPTIONAL ,
pub Affil OPTIONAL, -- publisher, required for book
cprt Date OPTIONAL, -- copyright date, " " "
part-sup VisibleString OPTIONAL , -- used in MEDLINE
language VisibleString DEFAULT "ENG" , -- put here for simplicity
prepub ENUMERATED { -- for prepublication citaions
submitted (1) , -- submitted, not accepted
in-press (2) , -- accepted, not published
other (255) } OPTIONAL }
Meeting ::= SEQUENCE {
number VisibleString ,
date Date ,
place Affil OPTIONAL }
END
/* objbibli.h
* ===========================================================================
*
* PUBLIC DOMAIN NOTICE
* National Center for Biotechnology Information
*
* This software/database is a "United States Government Work" under the
* terms of the United States Copyright Act. It was written as part of
* the author's official duties as a United States Government employee and
* thus cannot be copyrighted. This software/database is freely available
* to the public for use. The National Library of Medicine and the U.S.
* Government have not placed any restriction on its use or reproduction.
*
* Although all reasonable efforts have been taken to ensure the accuracy
* and reliability of the software and data, the NLM and the U.S.
* Government do not and cannot warrant the performance or results that
* may be obtained by using this software or data. The NLM and the U.S.
* Government disclaim all warranties, express or implied, including
* warranties of performance, merchantability or fitness for any particular
* purpose.
*
* Please cite the author in any work or product based on this material.
*
* ===========================================================================
*
* File Name: objbibli.h
*
* Author: James Ostell
*
* Version Creation Date: 1/1/91
*
* $Revision: 2.1 $
*
* File Description: Object manager interface for module NCBI-Biblio
*
* Modifications:
* --------------------------------------------------------------------------
* Date Name Description of modification
* ------- ---------- -----------------------------------------------------
*
*
* ==========================================================================
*/
#ifndef _NCBI_Biblio_
#define _NCBI_Biblio_
#ifndef _ASNTOOL_
#include <asn.h>
#endif
#ifndef _NCBI_General_
#include <objgen.h>
#endif
#ifdef __cplusplus
extern "C" {
#endif
/*****************************************************************************
*
* loader
*
*****************************************************************************/
extern Boolean BiblioAsnLoad PROTO((void));
/*****************************************************************************
*
* Affil
*
*****************************************************************************/
typedef struct affil {
Uint1 choice; /* [1]=str,[2]=std */
CharPtr affil, /* also used for str */
div,
city,
sub,
country,
street;
} Affil, PNTR AffilPtr;
extern AffilPtr AffilNew PROTO((void));
extern AffilPtr AffilFree PROTO((AffilPtr afp));
extern AffilPtr AffilAsnRead PROTO((AsnIoPtr aip, AsnTypePtr atp));
extern Boolean AffilAsnWrite PROTO((AffilPtr afp, AsnIoPtr aip, AsnTypePtr atp));
/*****************************************************************************
*
* AuthList
*
*****************************************************************************/
typedef struct authors {
Uint1 choice; /* [1]=std, [2]=ml, [3]=str (only on Cit-art,gen) */
ValNodePtr names; /* the SEQUENCE OF */
AffilPtr affil;
} AuthList, PNTR AuthListPtr;
extern AuthListPtr AuthListNew PROTO((void));
extern AuthListPtr AuthListFree PROTO((AuthListPtr asp));
extern AuthListPtr AuthListAsnRead PROTO((AsnIoPtr aip, AsnTypePtr atp));
extern Boolean AuthListAsnWrite PROTO((AuthListPtr afp, AsnIoPtr aip, AsnTypePtr atp));
Int2 AuthListMatch PROTO((AuthListPtr a, AuthListPtr b, Boolean all));
/*****************************************************************************
*
* Author
*
*****************************************************************************/
typedef struct author {
PersonIdPtr name;
Uint1 lr[2]; /* level[0], role[1] as in spec. 0=not used */
Uint1 is_corr; /* corresponding author? 255=not set, 0=false, 1=true */
AffilPtr affil;
} Author, PNTR AuthorPtr;
extern AuthorPtr AuthorNew PROTO((void));
extern AuthorPtr AuthorFree PROTO((AuthorPtr ap));
extern AuthorPtr AuthorAsnRead PROTO((AsnIoPtr aip, AsnTypePtr atp));
extern Boolean AuthorAsnWrite PROTO((AuthorPtr ap, AsnIoPtr aip, AsnTypePtr atp));
/*****************************************************************************
*
* Cit-art
*
*****************************************************************************/
typedef struct citart {
ValNodePtr title; /* choice[1]=name,[2]=tsub,[3]=trans */
AuthListPtr authors;
Uint1 from; /* [1]=journal,[2]=book,[3]=proc */
Pointer fromptr;
} CitArt, PNTR CitArtPtr;
extern CitArtPtr CitArtNew PROTO((void));
extern CitArtPtr CitArtFree PROTO((CitArtPtr cap));
extern CitArtPtr CitArtAsnRead PROTO((AsnIoPtr aip, AsnTypePtr atp));
extern Boolean CitArtAsnWrite PROTO((CitArtPtr cap, AsnIoPtr aip, AsnTypePtr atp));
Int2 CitArtMatch PROTO((CitArtPtr a, CitArtPtr b));
/*****************************************************************************
*
* Imprint
*
*****************************************************************************/
typedef struct imprint {
DatePtr date;
CharPtr volume,
issue,
pages,
section,
part_sup,
language;
DatePtr cprt; /* copy right date (for books) */
AffilPtr pub; /* publisher (for books) */
Uint1 prepub; /* 0=not set 1=submitted 2=in-press 255=other */
} Imprint, PNTR ImprintPtr;
extern ImprintPtr ImprintNew PROTO((void));
extern ImprintPtr ImprintFree PROTO((ImprintPtr cap));
extern ImprintPtr ImprintAsnRead PROTO((AsnIoPtr aip, AsnTypePtr atp));
extern Boolean ImprintAsnWrite PROTO((ImprintPtr cap, AsnIoPtr aip, AsnTypePtr atp));
Int2 ImprintMatch PROTO((ImprintPtr a, ImprintPtr b, Boolean all));
/*****************************************************************************
*
* Cit-jour
*
*****************************************************************************/
typedef struct citjour {
ValNodePtr title; /* choice in order of spec, 1=name,2=trans,etc */
ImprintPtr imp;
} CitJour, PNTR CitJourPtr;
extern CitJourPtr CitJourNew PROTO((void));
extern CitJourPtr CitJourFree PROTO((CitJourPtr cjp));
extern CitJourPtr CitJourAsnRead PROTO((AsnIoPtr aip, AsnTypePtr atp));
extern Boolean CitJourAsnWrite PROTO((CitJourPtr cjp, AsnIoPtr aip, AsnTypePtr atp));
Int2 CitJourMatch PROTO((CitJourPtr a, CitJourPtr b));
/*****************************************************************************
*
* Cit-book
*
*****************************************************************************/
typedef struct citbook {
ValNodePtr title, /* choice in order of spec, 1=name, 2=tsub, etc */
coll; /* ditto */
AuthListPtr authors;
ImprintPtr imp;
Uint1 othertype, /* 0=Cit-book, 1=Cit-proc, 2=Cit-let */
let_type; /* if Cit-let, 1=manuscript,2=letter,3=thesis */
Pointer otherdata; /* NULL, ValNodes, CharPtr man-id */
} CitBook, PNTR CitBookPtr;
extern CitBookPtr CitBookNew PROTO((void));
extern CitBookPtr CitBookFree PROTO((CitBookPtr cbp));
extern CitBookPtr CitBookAsnRead PROTO((AsnIoPtr aip, AsnTypePtr atp));
extern Boolean CitBookAsnWrite PROTO((CitBookPtr cbp, AsnIoPtr aip, AsnTypePtr atp));
Int2 CitBookMatch PROTO((CitBookPtr a, CitBookPtr b));
/*****************************************************************************
*
* Cit-sub
* Direct submission of data
*
*****************************************************************************/
typedef struct citsub {
AuthListPtr authors;
ImprintPtr imp;
Uint1 medium;
} CitSub, PNTR CitSubPtr;
extern CitSubPtr CitSubNew PROTO((void));
extern CitSubPtr CitSubFree PROTO((CitSubPtr cbp));
extern CitSubPtr CitSubAsnRead PROTO((AsnIoPtr aip, AsnTypePtr atp));
extern Boolean CitSubAsnWrite PROTO((CitSubPtr cbp, AsnIoPtr aip, AsnTypePtr atp));
Int2 CitSubMatch PROTO((CitSubPtr a, CitSubPtr b));
/*****************************************************************************
*
* Cit-proc
* uses otherdata in Cit-book
* chain of ValNodes
* choice ident Pointer type
* 1 number CharPtr
* 2 date DatePtr
* 3 place AffilPtr
*
*****************************************************************************/
extern CitBookPtr CitProcAsnRead PROTO((AsnIoPtr aip, AsnTypePtr atp));
extern Boolean CitProcAsnWrite PROTO((CitBookPtr cpp, AsnIoPtr aip, AsnTypePtr atp));
/*****************************************************************************
*
* Cit-let
* uses otherdata in Cit-book as CharPtr for man-id
*
*****************************************************************************/
extern CitBookPtr CitLetAsnRead PROTO((AsnIoPtr aip, AsnTypePtr atp));
extern Boolean CitLetAsnWrite PROTO((CitBookPtr cpp, AsnIoPtr aip, AsnTypePtr atp));
/*****************************************************************************
*
* Cit-pat
*
*****************************************************************************/
typedef struct citpat {
CharPtr title;
AuthListPtr authors;
CharPtr country,
doc_type,
number;
DatePtr date_issue;
CharPtr _class,
app_number;
DatePtr app_date;
} CitPat, PNTR CitPatPtr;
extern CitPatPtr CitPatNew PROTO((void));
extern CitPatPtr CitPatFree PROTO((CitPatPtr cpp));
extern CitPatPtr CitPatAsnRead PROTO((AsnIoPtr aip, AsnTypePtr atp));
extern Boolean CitPatAsnWrite PROTO((CitPatPtr cpp, AsnIoPtr aip, AsnTypePtr atp));
/*****************************************************************************
*
* Id-pat
*
*****************************************************************************/
typedef struct idpat {
CharPtr country,
number, /** actually CHOICE of number or app_number */
app_number;
} IdPat, PNTR IdPatPtr;
extern IdPatPtr IdPatNew PROTO((void));
extern IdPatPtr IdPatFree PROTO((IdPatPtr ipp));
extern IdPatPtr IdPatAsnRead PROTO((AsnIoPtr aip, AsnTypePtr atp));
extern Boolean IdPatAsnWrite PROTO((IdPatPtr ipp, AsnIoPtr aip, AsnTypePtr atp));
extern Boolean IdPatMatch PROTO((IdPatPtr a, IdPatPtr b));
/*****************************************************************************
*
* Cit-gen
*
*****************************************************************************/
typedef struct cit_gen {
CharPtr cit;
AuthListPtr authors;
Int4 muid; /* medline uid, -1 if not set */
ValNodePtr journal; /* journal/book Title */
CharPtr volume,
issue,
pages;
DatePtr date;
Int2 serial_number; /* for GenBank style references (-1 = not used)*/
CharPtr title; /* a specific title (in addition to cit or journal) */
} CitGen, PNTR CitGenPtr;
extern CitGenPtr CitGenNew PROTO((void));
extern CitGenPtr CitGenFree PROTO((CitGenPtr cgp));
extern CitGenPtr CitGenAsnRead PROTO((AsnIoPtr aip, AsnTypePtr atp));
extern Boolean CitGenAsnWrite PROTO((CitGenPtr cgp, AsnIoPtr aip, AsnTypePtr atp));
Int2 CitGenMatch PROTO((CitGenPtr a, CitGenPtr b, Boolean all));
/*****************************************************************************
*
* Title
*
*****************************************************************************/
extern ValNodePtr TitleFree PROTO((ValNodePtr anp));
extern ValNodePtr TitleAsnRead PROTO((AsnIoPtr aip, AsnTypePtr atp));
extern Boolean TitleAsnWrite PROTO((ValNodePtr anp, AsnIoPtr aip, AsnTypePtr atp));
Int2 TitleMatch PROTO((ValNodePtr a, ValNodePtr b, Uint1 type));
#define Cit_title_name ( (Uint1) 1)
#define Cit_title_tsub ( (Uint1) 2)
#define Cit_title_trans ( (Uint1) 3)
#define Cit_title_jta ( (Uint1) 4)
#define Cit_title_iso_jta ( (Uint1) 5)
#define Cit_title_ml_jta ( (Uint1) 6)
#define Cit_title_coden ( (Uint1) 7)
#define Cit_title_issn ( (Uint1) 8)
#define Cit_title_abr ( (Uint1) 9)
#define Cit_title_isbn ( (Uint1) 10)
#ifdef __cplusplus
}
#endif
#endif
--$Revision: 2.0 $
--********************************************************************
--
-- Publication common set
-- James Ostell, 1990
--
-- This is the base class definitions for Publications of all sorts
--
--******************************************************************** NCBI-Pub DEFINITIONS ::= BEGIN EXPORTS Pub, Pub-set, Pub-equiv; IMPORTS Medline-entry FROM NCBI-Medline
Cit-art, Cit-jour, Cit-book, Cit-proc, Cit-pat, Id-pat, Cit-gen,
Cit-let, Cit-sub FROM NCBI-Biblio; Pub ::= CHOICE {
gen Cit-gen , -- general or generic unparsed
sub Cit-sub , -- submission
medline Medline-entry ,
muid INTEGER , -- medline uid
article Cit-art ,
journal Cit-jour ,
book Cit-book ,
proc Cit-proc , -- proceedings of a meeting
patent Cit-pat ,
pat-id Id-pat , -- identify a patent
man Cit-let , -- manuscript, thesis, or letter
equiv Pub-equiv } -- to cite a variety of ways Pub-equiv ::= SET OF Pub -- equivalent identifiers for same citation Pub-set ::= CHOICE {
pub SET OF Pub ,
medline SET OF Medline-entry ,
article SET OF Cit-art ,
journal SET OF Cit-jour ,
book SET OF Cit-book ,
proc SET OF Cit-proc , -- proceedings of a meeting
patent SET OF Cit-pat } END
/* objpub.h
* ===========================================================================
*
* PUBLIC DOMAIN NOTICE
* National Center for Biotechnology Information
*
* This software/database is a "United States Government Work" under the
* terms of the United States Copyright Act. It was written as part of
* the author's official duties as a United States Government employee and
* thus cannot be copyrighted. This software/database is freely available
* to the public for use. The National Library of Medicine and the U.S.
* Government have not placed any restriction on its use or reproduction.
*
* Although all reasonable efforts have been taken to ensure the accuracy
* and reliability of the software and data, the NLM and the U.S.
* Government do not and cannot warrant the performance or results that
* may be obtained by using this software or data. The NLM and the U.S.
* Government disclaim all warranties, express or implied, including
* warranties of performance, merchantability or fitness for any particular
* purpose.
*
* Please cite the author in any work or product based on this material.
*
* ===========================================================================
*
* File Name: objpub.h
*
* Author: James Ostell
*
* Version Creation Date: 4/1/91
*
* $Revision: 2.1 $
*
* File Description: Object manager interface for module NCBI-Pub
*
* Modifications:
* --------------------------------------------------------------------------
* Date Name Description of modification
* ------- ---------- -----------------------------------------------------
*
*
* ==========================================================================
*/
#ifndef _NCBI_Pub_
#define _NCBI_Pub_
#ifndef _ASNTOOL_
#include <asn.h>
#endif
#ifndef _NCBI_Biblio_
#include <objbibli.h>
#endif
#ifndef _NCBI_Medline_
#include <objmedli.h>
#endif
#ifdef __cplusplus extern "C" {
#endif
/*****************************************************************************
*
* loader
*
*****************************************************************************/ extern Boolean PubAsnLoad PROTO((void));
/*****************************************************************************
*
* internal structures for NCBI-Pub objects
*
*****************************************************************************/
/*****************************************************************************
*
* Pub is a choice using an ValNode, most types in data.ptrvalue
* choice:
* 0 = not set
1 = gen Cit-gen , -- general or generic unparsed
2 = sub Cit-sub , -- submission
3 = medline Medline-entry ,
4 = muid INTEGER , -- medline uid (stored in data.intvalue)
5 = article Cit-art ,
6 = journal Cit-jour ,
7 = book Cit-book ,
8 = proc Cit-proc , -- proceedings of a meeting
9 = patent Cit-pat ,
10 = pat-id Id-pat , -- identify a patent
11 = man Cit-let -- manuscript or letter
12 = equiv Pub-equiv -- set of equivalent citation forms for 1 pub
*
*****************************************************************************/ Boolean PubAsnWrite PROTO((ValNodePtr anp, AsnIoPtr aip, AsnTypePtr atp)); ValNodePtr PubAsnRead PROTO((AsnIoPtr aip, AsnTypePtr atp)); ValNodePtr PubFree PROTO((ValNodePtr anp));
#define PUB_Gen 1
#define PUB_Sub 2
#define PUB_Medline 3
#define PUB_Muid 4
#define PUB_Article 5
#define PUB_Journal 6
#define PUB_Book 7
#define PUB_Proc 8
#define PUB_Patent 9
#define PUB_Pat_id 10
#define PUB_Man 11
#define PUB_Equiv 12
/****
* Pub and PubEquiv Matching functions (same citation, not same form)
* PubMatch() returns
* 0 = point to same citation
* 1,-1 = same pub type, but different
* 2,-2 = different put types, don't match
* PubEquivMatch() returns
* 0 = point to same citation
* 1,-1 = point to different citations
*****/ Int2 PubMatch PROTO((ValNodePtr a, ValNodePtr b)); Int2 PubEquivMatch PROTO((ValNodePtr a, ValNodePtr b));
/*****************************************************************************
*
* PubSet is a choice using an ValNode, PubSet->data.ptrvalue is chain of
* Pubs (ValNodes) holding data for set for all types.
* PubSet->choice:
* 0 = not set
1 = pub Pub -- set of real Pubs
-- the rest are implemented as Pubs anyway
3 = medline Medline-entry ,
5 = article Cit-art ,
6 = journal Cit-jour ,
7 = book Cit-book ,
8 = proc Cit-proc , -- proceedings of a meeting
9 = patent Cit-pat ,
*
*****************************************************************************/ Boolean PubSetAsnWrite PROTO((ValNodePtr anp, AsnIoPtr aip, AsnTypePtr atp)); ValNodePtr PubSetAsnRead PROTO((AsnIoPtr aip, AsnTypePtr atp)); ValNodePtr PubSetFree PROTO((ValNodePtr anp));
/*****************************************************************************
*
* PubEquiv is just a chain of Pubs (ValNodes)
*
*****************************************************************************/ Boolean PubEquivAsnWrite PROTO((ValNodePtr anp, AsnIoPtr aip, AsnTypePtr atp)); ValNodePtr PubEquivAsnRead PROTO((AsnIoPtr aip, AsnTypePtr atp)); ValNodePtr PubEquivFree PROTO((ValNodePtr anp));
#ifdef __cplusplus
}
#endif
#endif